@escape-game-over/atlas 0.1.88 → 0.1.90

package/package.json

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

package/src/index.ts

@@ -262,8 +262,10 @@ export {
     enableRoutes,
     type FamilyMember,
     type FamilyMemberInput,
+    type FamilyMemberSlugs,
     type FamilyOptions,
     familyGuard,
+    familyMemberSlugs,
     type RouteIdsOf,
 } from "./routes/family.ts";
 export type { RouteEntry } from "./routes/resolve.ts";

package/src/routes/define.ts

@@ -204,7 +204,12 @@ type InheritedDepthMismatch<
 > = K extends keyof Base
     ? Base[K] extends { readonly slugByLocale?: infer M }
         ? {
-              [L in keyof M]: L extends OverriddenLocales<T, K>
+              // `-?`: the translations are a `Partial`, and a mapped type keeps
+              // its `?`, so every entry would read `never | undefined` and the
+              // lookup below `undefined` — not `never` — failing every `slug`
+              // override of a route whose translations are optional, family
+              // members among them.
+              [L in keyof M]-?: L extends OverriddenLocales<T, K>
                   ? never
                   : M[L] extends infer V extends string
                     ? SegmentCount<V> extends Depth

package/src/routes/family.ts

@@ -75,6 +75,113 @@ export interface FamilyOptions<L extends string> {
     readonly sitemap?: RouteSitemap;
 }
 
+/** Per-locale translations, keyed by locale. */
+type ByLocale = Readonly<Record<string, string>>;
+
+/** One locale's path: its translated halves where it has them, else the defaults. */
+type JoinedSlug<
+    Prefix extends string,
+    PrefixBy extends ByLocale,
+    Segment extends string,
+    SegmentBy extends ByLocale,
+    K,
+> = `${K extends keyof PrefixBy ? PrefixBy[K] : Prefix}/${K extends keyof SegmentBy
+    ? SegmentBy[K]
+    : Segment}`;
+
+/** What {@link familyMemberSlugs} returns: literal paths, so depth checks still apply. */
+export type FamilyMemberSlugs<
+    Prefix extends string,
+    Segment extends string,
+    PrefixBy extends ByLocale = Record<never, never>,
+    SegmentBy extends ByLocale = Record<never, never>,
+> = { readonly slug: `${Prefix}/${Segment}` } & ([
+    keyof PrefixBy | keyof SegmentBy,
+] extends [never]
+    ? unknown
+    : {
+          readonly slugByLocale: {
+              readonly [K in keyof PrefixBy | keyof SegmentBy]: JoinedSlug<
+                  Prefix,
+                  PrefixBy,
+                  Segment,
+                  SegmentBy,
+                  K
+              >;
+          };
+      });
+
+/**
+ * A family member's paths, in every locale, as {@link routeFamily} composes
+ * them — for a project that gives one member a segment of its own.
+ *
+ * ```ts
+ * overrideRoutes: {
+ *     "rooms-illuminati": {
+ *         enabled: true,
+ *         ...familyMemberSlugs("rooms", "the-da-vinci-code", {
+ *             prefixByLocale: ROOM_PREFIX_BY_LOCALE,
+ *         }),
+ *     },
+ * }
+ * ```
+ *
+ * Overriding only `slug` would move the default locale and leave every
+ * translated path at the family's id, at the same depth, so nothing would
+ * catch it. This restates them all from the same join the family used. Pass
+ * the family's `prefixByLocale`, so the member stays under its siblings in
+ * every locale.
+ */
+export function familyMemberSlugs<
+    const Prefix extends string,
+    const Segment extends string,
+    const PrefixBy extends ByLocale = Record<never, never>,
+    const SegmentBy extends ByLocale = Record<never, never>,
+>(
+    prefix: Prefix,
+    segment: Segment,
+    translations: {
+        readonly prefixByLocale?: PrefixBy;
+        readonly segmentByLocale?: SegmentBy;
+    } = {}
+): FamilyMemberSlugs<Prefix, Segment, PrefixBy, SegmentBy> {
+    const slugByLocale = joinByLocale(
+        prefix,
+        segment,
+        translations.prefixByLocale,
+        translations.segmentByLocale
+    );
+    return {
+        slug: `${prefix}/${segment}`,
+        ...(slugByLocale === undefined ? {} : { slugByLocale }),
+    } as never;
+}
+
+/**
+ * The translated paths of one member, or `undefined` where neither half is
+ * translated. A locale gets one when either half is; the untranslated half
+ * falls back to the default, so every locale sits at the same depth by
+ * construction.
+ */
+function joinByLocale(
+    prefix: string,
+    segment: string,
+    prefixByLocale: Readonly<Partial<Record<string, string>>> | undefined,
+    segmentByLocale: Readonly<Partial<Record<string, string>>> | undefined
+): Record<string, string> | undefined {
+    const locales = new Set([
+        ...Object.keys(prefixByLocale ?? {}),
+        ...Object.keys(segmentByLocale ?? {}),
+    ]);
+    if (locales.size === 0) return undefined;
+    const slugByLocale: Record<string, string> = {};
+    for (const locale of locales) {
+        slugByLocale[locale] =
+            `${prefixByLocale?.[locale] ?? prefix}/${segmentByLocale?.[locale] ?? segment}`;
+    }
+    return slugByLocale;
+}
+
 /**
  * Expands a family into ordinary route entries, ready to spread into
  * `defineRoutes`.
@@ -127,26 +234,19 @@ export function routeFamily<
         const segmentByLocale =
             typeof member === "string" ? undefined : member.segmentByLocale;
 
-        // A locale gets a translated slug when either half is translated; the
-        // untranslated half falls back to what the default slug uses, so the
-        // number of segments is the same in every locale by construction.
-        const locales = new Set([
-            ...Object.keys(options?.prefixByLocale ?? {}),
-            ...Object.keys(segmentByLocale ?? {}),
-        ]);
-        const slugByLocale: Record<string, string> = {};
-        for (const locale of locales) {
-            const localePrefix =
-                options?.prefixByLocale?.[locale as LocalesOf<C>] ?? prefix;
-            const localeSegment =
-                segmentByLocale?.[locale as LocalesOf<C>] ?? id;
-            slugByLocale[locale] = `${localePrefix}/${localeSegment}`;
-        }
+        // The same join `familyMemberSlugs` gives a project, so a member it
+        // moves sits exactly where the family would have put it.
+        const slugByLocale = joinByLocale(
+            prefix,
+            id,
+            options?.prefixByLocale,
+            segmentByLocale
+        );
 
         routes[`${prefix.replaceAll("/", "-")}-${id}`] = {
             slug: `${prefix}/${id}`,
             enabled: options?.enabled ?? true,
-            ...(locales.size > 0
+            ...(slugByLocale !== undefined
                 ? {
                       slugByLocale: slugByLocale as Readonly<
                           Partial<Record<LocalesOf<C>, string>>