@escape-game-over/atlas 0.1.98 → 0.1.100

package/package.json

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

package/src/hours.ts

@@ -217,6 +217,97 @@ export function formatHours(
 ): readonly FormattedHours[] {
     const between = format.between ?? "–";
     const and = format.and ?? ", ";
+    const { dayName, time } = printer(format);
+
+    return groupHours(hours, format.weekStart).map((group) => ({
+        days: group.runs.map((run) => runName(run, dayName, between)).join(and),
+        weekdays: group.days,
+        times: timesOf(group, format.closed, time, between, and),
+    }));
+}
+
+/** How to say a week in a sentence: `HoursFormat` without its separators. */
+export type HoursSentenceFormat = Omit<HoursFormat, "and">;
+
+/**
+ * Each language's semicolon, between one group of days and the next. `Intl`
+ * has no list form for it, and it is punctuation rather than copy, so it lives
+ * here. A language missing from this table throws rather than borrowing the
+ * English one: add it here.
+ */
+const SEMICOLONS: Readonly<Record<string, string>> = {
+    ar: "؛ ",
+    de: "; ",
+    el: "· ",
+    en: "; ",
+    es: "; ",
+    // A narrow no-break space before it, as French sets it.
+    fr: "\u202F; ",
+    hu: "; ",
+    it: "; ",
+    pt: "; ",
+    ru: "; ",
+    sv: "; ",
+};
+
+function semicolonFor(locale: string): string {
+    const { language } = new Intl.Locale(locale);
+    const semicolon = Object.hasOwn(SEMICOLONS, language)
+        ? SEMICOLONS[language]
+        : undefined;
+    if (semicolon === undefined) {
+        throw new Error(
+            `hoursSentence has no semicolon for "${language}" (${locale}). Add it to SEMICOLONS in hours.ts.`
+        );
+    }
+    return semicolon;
+}
+
+/**
+ * The week as one sentence, for copy that quotes it: `Monday–Thursday and
+ * Sunday 14:00–23:30; Friday–Saturday 14:00–00:45`.
+ *
+ * Days and times join with the locale's own "and" (`Intl.ListFormat`), so a
+ * sentence in Arabic reads `الاثنين–الخميس والأحد` rather than borrowing an
+ * English comma; groups with the language's semicolon (`؛` in Arabic). No
+ * closing full stop: the copy around it decides that.
+ */
+export function hoursSentence(
+    hours: WeeklyHours,
+    format: HoursSentenceFormat
+): string {
+    const between = format.between ?? "–";
+    const semicolon = semicolonFor(format.locale);
+    const { dayName, time } = printer(format);
+    const list = new Intl.ListFormat(format.locale, {
+        type: "conjunction",
+        style: "long",
+    });
+    const joined = (parts: readonly string[]) => list.format(parts);
+
+    return groupHours(hours, format.weekStart)
+        .map((group) => {
+            const days = joined(
+                group.runs.map((run) => runName(run, dayName, between))
+            );
+            const times =
+                group.hours === "closed"
+                    ? format.closed
+                    : joined(
+                          group.hours.map(
+                              (range) =>
+                                  `${time(range.opens)}${between}${time(range.closes)}`
+                          )
+                      );
+            return `${days} ${times}`;
+        })
+        .join(semicolon);
+}
+
+/** Day names and times as `format` prints them. */
+function printer(
+    format: Pick<HoursFormat, "locale" | "weekday" | "hourCycle">
+) {
     // 2024-01-01 was a Monday, so `WEEK[i]` falls on the 1st plus `i`.
     const names = new Intl.DateTimeFormat(format.locale, {
         weekday: format.weekday ?? "short",
@@ -247,26 +338,35 @@ export function formatHours(
                       )
                   )
               );
+    return { dayName, time };
+}
 
-    return groupHours(hours, format.weekStart).map((group) => ({
-        days: group.runs
-            .map(([first, last]) =>
-                first === last
-                    ? dayName(first)
-                    : `${dayName(first)}${between}${dayName(last)}`
-            )
-            .join(and),
-        weekdays: group.days,
-        times:
-            group.hours === "closed"
-                ? format.closed
-                : group.hours
-                      .map(
-                          (range) =>
-                              `${time(range.opens)}${between}${time(range.closes)}`
-                      )
-                      .join(and),
-    }));
+/** A run of one day prints as one name — `Sun`, not `Sun–Sun`. */
+function runName(
+    [first, last]: HoursGroup["runs"][number],
+    dayName: (day: Weekday) => string,
+    between: string
+): string {
+    return first === last
+        ? dayName(first)
+        : `${dayName(first)}${between}${dayName(last)}`;
+}
+
+function timesOf(
+    group: HoursGroup,
+    closed: string,
+    time: (at: TimeOfDay) => string,
+    between: string,
+    and: string
+): string {
+    return group.hours === "closed"
+        ? closed
+        : group.hours
+              .map(
+                  (range) =>
+                      `${time(range.opens)}${between}${time(range.closes)}`
+              )
+              .join(and);
 }
 
 /** Minutes since midnight, for comparing two times. */

package/src/index.ts

@@ -123,6 +123,8 @@ export {
     groupHours,
     type HoursFormat,
     type HoursGroup,
+    type HoursSentenceFormat,
+    hoursSentence,
     type OpenStatus,
     openStatus,
     type TimeOfDay,