initial commit

apps/web/app/lib/route-handle.ts

@@ -0,0 +1,59 @@
+/* ============================================================================
+   ROUTE HANDLE
+   ----------------------------------------------------------------------------
+   The shell reads a few presentation decisions off the deepest route's
+   `handle`, so a page can flip the header or footer to the light surface
+   without the root layout knowing anything about that page.
+
+     export const handle = { navSurface: "light" } satisfies RouteHandle;
+   ========================================================================= */
+
+/** Which tier-2 surface a shell element paints. `:root` is the dark one. */
+export type ShellSurface = "dark" | "light";
+
+export interface RouteHandle {
+  /** Surface for the sticky header. Default "dark". */
+  readonly navSurface?: ShellSurface;
+  /** Surface for the footer. Default "dark". */
+  readonly footerSurface?: ShellSurface;
+  /**
+   * Override the canonical pathname the shell emits for this route - e.g. a
+   * paginated listing that should point page 2 at page 1. Locale-prefixed.
+   */
+  readonly canonicalPath?: string;
+  /**
+   * "This page emits its own canonical + hreflang - do not add the shell's
+   * prefix-swapped pair." Set by detail routes, whose Arabic counterpart has
+   * its own Strapi slug, so swapping the locale prefix alone points the
+   * alternate at a URL that does not exist.
+   */
+  readonly selfAlternates?: boolean;
+  /** Anything a route wants to hang off its own handle. */
+  readonly [key: string]: unknown;
+}
+
+function readSurface(value: unknown): ShellSurface | undefined {
+  return value === "dark" || value === "light" ? value : undefined;
+}
+
+export function readNavSurface(handle: Record<string, unknown>): ShellSurface | undefined {
+  return readSurface(handle.navSurface);
+}
+
+export function readFooterSurface(
+  handle: Record<string, unknown>,
+): ShellSurface | undefined {
+  return readSurface(handle.footerSurface);
+}
+
+export function readCanonicalPath(
+  handle: Record<string, unknown>,
+): string | undefined {
+  return typeof handle.canonicalPath === "string" ? handle.canonicalPath : undefined;
+}
+
+export function readSelfAlternates(
+  handle: Record<string, unknown>,
+): boolean | undefined {
+  return handle.selfAlternates === true ? true : undefined;
+}