create-ailk 0.26.0 → 0.28.0

package/templates/apps/web/lib/page-chrome.ts

@@ -0,0 +1,367 @@
+/**
+ * Per-page chrome (#10049 D3) — which header and footer a page wears, and
+ * whether the home is a deck.
+ *
+ * Four levels, most specific first: the page's own frontmatter (`header:`,
+ * `footer:`, `layout:`), its route family's key in `_site.mdx` (`blog:`,
+ * `docs:`, …), the site defaults in `_site.mdx` (`header.style`,
+ * `footer.style`, `layout`), and last the design's own knobs in the
+ * generated `site-chrome.ts`. A site that sets nothing resolves to exactly
+ * the chrome the design gave it before this file existed.
+ *
+ * Blog posts and docs pages are served by the docs-blog slice, which this
+ * base file must never import, so they take their `blog:` / `docs:` family
+ * or the site default; their own frontmatter is not read here.
+ *
+ * `_site.mdx` is read locally rather than through
+ * `@working-theory/site-config/server`, as `site-header.ts` does (#1567).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  getMdxSource,
+  type SchemaOrgType,
+} from "@working-theory/page-renderer";
+import {
+  HeaderStyleSchema,
+  ROUTE_FAMILY_KEYS,
+  SiteConfigSchema,
+  type FooterStyle,
+  type HeaderStyle,
+  type RouteFamilyChrome,
+  type RouteFamilyKey,
+  type SiteLayout,
+} from "@working-theory/site-config/schema";
+import { ROUTES } from "@working-theory/templates/routes";
+import { readLocales } from "@working-theory/web-i18n";
+import { cache } from "react";
+import { parse as parseYaml } from "yaml";
+import type { ZodType } from "zod";
+
+import { normalizeRoutePath } from "./closing-footer-path";
+import {
+  isAlwaysScaffolded,
+  matchesRoute,
+  resolveTypeAndSlug,
+} from "./deck-page";
+import { toInternalDocsPath } from "./docs-path";
+import { SERVICES_ROUTE, toInternalServicesPath } from "./services-path";
+import { resolveContentRoot } from "./site-brand";
+
+/** The chrome settings a site sets in `_site.mdx`. */
+export interface SiteChromeSettings {
+  headerStyle?: HeaderStyle;
+  footerStyle?: FooterStyle;
+  layout?: SiteLayout;
+  families: Partial<Record<RouteFamilyKey, RouteFamilyChrome>>;
+}
+
+/** The chrome fields a page's own frontmatter sets. */
+export interface PageChromeFields {
+  header?: HeaderStyle;
+  footer?: FooterStyle;
+  layout?: SiteLayout;
+}
+
+/**
+ * The design knobs the template level reads — a structural slice of the
+ * generated `SiteChrome`, so a scaffold generated before `innerPages` or
+ * `chromeStyle` existed still compiles.
+ */
+export interface ChromeKnobs {
+  home: SiteLayout;
+  footer: "columns" | "centered";
+  innerPages?: "bare";
+  chromeStyle?: "minimal";
+}
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+const warnedPaths = new Set<string>();
+
+/** One warning per field path per process, naming the path and the Zod message — never the value. */
+function warnOnce(path: string, message: string): void {
+  if (warnedPaths.has(path)) return;
+  warnedPaths.add(path);
+  console.warn(`[page-chrome] ignoring _site.mdx ${path}: ${message}`);
+}
+
+/** `value` parsed by `schema`, else `undefined` with a warning under `path`. */
+function validated<T>(
+  schema: ZodType<T>,
+  value: unknown,
+  path: string,
+): T | undefined {
+  if (value === undefined) return undefined;
+  const parsed = schema.safeParse(value);
+  if (parsed.success) return parsed.data;
+  const issue = parsed.error.issues[0];
+  warnOnce(
+    [path, ...(issue?.path ?? [])].join("."),
+    issue?.message ?? "invalid",
+  );
+  return undefined;
+}
+
+/**
+ * `_site.mdx`'s chrome keys. Each key validates on its own, so one bad key
+ * drops only itself; an absent file, frontmatter or key is silent.
+ */
+export const readSiteChromeSettings = cache(
+  function readSiteChromeSettings(): SiteChromeSettings {
+    try {
+      const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
+      const match = FRONTMATTER_RE.exec(raw);
+      if (!match) return { families: {} };
+      const fm: unknown = parseYaml(match[1] ?? "");
+      if (!fm || typeof fm !== "object") return { families: {} };
+      const record = fm as Record<string, unknown>;
+
+      const settings: SiteChromeSettings = { families: {} };
+      const header = record["header"];
+      const headerStyle =
+        header && typeof header === "object"
+          ? validated(
+              HeaderStyleSchema,
+              (header as Record<string, unknown>)["style"],
+              "header.style",
+            )
+          : undefined;
+      if (headerStyle !== undefined) settings.headerStyle = headerStyle;
+      const footerStyle = validated(
+        SiteConfigSchema.shape.footer,
+        record["footer"],
+        "footer",
+      )?.style;
+      if (footerStyle !== undefined) settings.footerStyle = footerStyle;
+      const layout = validated(
+        SiteConfigSchema.shape.layout,
+        record["layout"],
+        "layout",
+      );
+      if (layout !== undefined) settings.layout = layout;
+      for (const key of ROUTE_FAMILY_KEYS) {
+        const family = validated(SiteConfigSchema.shape[key], record[key], key);
+        if (family !== undefined) settings.families[key] = family;
+      }
+      return settings;
+    } catch (err) {
+      // An absent file is silent; unreadable frontmatter is worth one warning.
+      if ((err as { code?: unknown }).code !== "ENOENT") {
+        warnOnce("frontmatter", "could not be read");
+      }
+      return { families: {} };
+    }
+  },
+);
+
+function camelCase(prefix: string): string {
+  return prefix
+    .replace(/^\//, "")
+    .replace(/-([a-z])/g, (_m, c: string) => c.toUpperCase());
+}
+
+/** Whether `segments` match a routes-map pattern, `:...slug` taking one or more segments. */
+function matchesPattern(pattern: string, segments: readonly string[]): boolean {
+  const parts = pattern.split("/").filter((part) => part.length > 0);
+  for (let i = 0; i < parts.length; i += 1) {
+    const part = parts[i] ?? "";
+    if (part.startsWith(":...")) return segments.length > i;
+    if (i >= segments.length) return false;
+    if (!part.startsWith(":") && part !== segments[i]) return false;
+  }
+  return parts.length === segments.length;
+}
+
+/**
+ * The route family a pathname belongs to, else `null`: the first routes-map
+ * hub whose prefix is the path, prefixes it, or whose detail pattern matches
+ * it. A site's moved docs are mapped back onto `/docs` first, and its moved
+ * services onto `/services` (#10043 D9).
+ */
+export function routeFamilyOf(
+  pathname: string,
+  locales: readonly string[],
+): RouteFamilyKey | null {
+  const bare = normalizeRoutePath(pathname, locales);
+  const path = toInternalDocsPath(bare) ?? toInternalServicesPath(bare) ?? bare;
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  for (const row of ROUTES) {
+    if (!row.hub) continue;
+    const { prefix, detailPattern } = row.hub;
+    if (
+      path === prefix ||
+      path.startsWith(`${prefix}/`) ||
+      matchesPattern(detailPattern, segments)
+    ) {
+      const key = camelCase(prefix);
+      return (ROUTE_FAMILY_KEYS as readonly string[]).includes(key)
+        ? (key as RouteFamilyKey)
+        : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The MDX content pages that could serve `pathname`, in the order Next.js
+ * tries them — `deckCandidates`' walk over every content row rather than the
+ * deck routes. Blog posts and docs pages live outside `content/`, so they are
+ * never candidates.
+ */
+export function chromePageCandidates(
+  pathname: string,
+  locales: readonly string[],
+): Array<{ type: SchemaOrgType; slug: string }> {
+  const normalized = normalizeRoutePath(pathname, locales);
+  // #10043 D9 — a site's moved services are mapped back onto `/services`.
+  const path = toInternalServicesPath(normalized) ?? normalized;
+  if (path === "/") return [{ type: "HomePage", slug: "home" }];
+  const segments = path.split("/").filter((segment) => segment.length > 0);
+  // A service under its category (`/services/<category>/<slug>`): the nested
+  // row names no content directory, so the walk below would never name it.
+  if (segments.length === 3 && segments[0] === SERVICES_ROUTE.slice(1)) {
+    return [{ type: "Service", slug: segments[2]! }];
+  }
+  const candidates: Array<{ type: SchemaOrgType; slug: string }> = [];
+
+  for (const row of ROUTES) {
+    if (!row.contentPath?.startsWith("content/")) continue;
+    if (!matchesRoute(row.route, segments)) continue;
+    const resolved = resolveTypeAndSlug(row, row.route, segments);
+    if (resolved) {
+      candidates.push(resolved);
+      break;
+    }
+  }
+
+  if (segments.length === 1 && !isAlwaysScaffolded(path)) {
+    const slug = segments[0];
+    if (slug !== undefined) {
+      candidates.push({ type: "LandingPage", slug });
+      candidates.push({ type: "BlogList", slug });
+    }
+  }
+  return candidates;
+}
+
+/**
+ * The page's own chrome frontmatter — the first candidate with a source —
+ * else `{}`. A read that throws answers `{}`: the page's own render surfaces
+ * the error. Per-request memoised.
+ */
+export const resolveChromePage = cache(async function resolveChromePage(
+  pathname: string,
+  locale: string,
+): Promise<PageChromeFields> {
+  try {
+    for (const candidate of chromePageCandidates(pathname, readLocales())) {
+      const source = await getMdxSource(candidate.type, candidate.slug, locale);
+      if (!source) continue;
+      const { header, footer, layout } = source.frontmatter as PageChromeFields;
+      return {
+        ...(header !== undefined ? { header } : {}),
+        ...(footer !== undefined ? { footer } : {}),
+        ...(layout !== undefined ? { layout } : {}),
+      };
+    }
+  } catch {
+    return {};
+  }
+  return {};
+});
+
+/** The home's layout: its own frontmatter, else the site's, else the design's. */
+export function resolveHomeLayout(
+  site: SiteChromeSettings,
+  home: PageChromeFields,
+  chrome: Pick<ChromeKnobs, "home">,
+): SiteLayout {
+  return home.layout ?? site.layout ?? chrome.home;
+}
+
+export interface PageChromeInput {
+  isHome: boolean;
+  /** The resolved home layout is a deck. */
+  homeIsDeck: boolean;
+  family: RouteFamilyKey | null;
+  page: PageChromeFields;
+  site: SiteChromeSettings;
+  chrome: ChromeKnobs;
+  /** The page is listed in the design's `closingFooterPaths`. */
+  closingListed: boolean;
+}
+
+export interface ResolvedChrome {
+  header: HeaderStyle;
+  /** No page, family or site value set the header — the design's own treatment applies. */
+  headerFromTemplate: boolean;
+  /** `line` is the design's one-bar footer on a bare inner page; never a site value. */
+  footer: FooterStyle | "line";
+}
+
+/** The design's own header and footer for a page (#10049 D3's template table). */
+function templateChrome(
+  input: PageChromeInput,
+): Pick<ResolvedChrome, "header" | "footer"> {
+  const { chrome } = input;
+  if (input.isHome) {
+    if (input.homeIsDeck && chrome.home === "deck") {
+      return {
+        header: "bare",
+        footer: chrome.chromeStyle === "minimal" ? "closing" : chrome.footer,
+      };
+    }
+    return { header: "full", footer: chrome.footer };
+  }
+  if (input.closingListed) {
+    return {
+      header: chrome.innerPages === "bare" ? "bare" : "full",
+      footer: "closing",
+    };
+  }
+  if (chrome.innerPages === "bare") return { header: "bare", footer: "line" };
+  return { header: "full", footer: chrome.footer };
+}
+
+/**
+ * The home's layout and chrome — the one resolution both the layout and the
+ * home page read, so the bar and the landing can never disagree.
+ */
+export async function resolveHomeChrome(
+  locale: string,
+  chrome: ChromeKnobs,
+): Promise<{ layout: SiteLayout; chrome: ResolvedChrome; site: SiteChromeSettings }> {
+  const site = readSiteChromeSettings();
+  const page = await resolveChromePage("/", locale);
+  const layout = resolveHomeLayout(site, page, chrome);
+  return {
+    layout,
+    site,
+    chrome: resolvePageChrome({
+      isHome: true,
+      homeIsDeck: layout === "deck",
+      family: null,
+      page,
+      site,
+      chrome,
+      closingListed: false,
+    }),
+  };
+}
+
+/** Each axis takes the first value set: page → route family → site → design. */
+export function resolvePageChrome(input: PageChromeInput): ResolvedChrome {
+  const template = templateChrome(input);
+  const family =
+    input.family !== null ? input.site.families[input.family] : undefined;
+  const header = input.page.header ?? family?.header ?? input.site.headerStyle;
+  const footer = input.page.footer ?? family?.footer ?? input.site.footerStyle;
+  return {
+    header: header ?? template.header,
+    headerFromTemplate: header === undefined,
+    footer: footer ?? template.footer,
+  };
+}

package/templates/apps/web/lib/posting-title.ts

@@ -5,13 +5,35 @@
  * is `/careers/<slug>`'s. In `lib/` (#8849 D9), not a route directory, so
  * every scaffold carries it: the `signal-collectors` walk and the Free apply
  * page (`careers/[slug]/[action]`) both read it.
+ *
+ * #10054 D2 — both pages read the posting through `postingForApply`, which
+ * also returns the magnet the posting names (`applicationFlow`, checked as a
+ * flow slug by the frontmatter schema); one read serves both.
  */
 import { getMdxSource } from "@working-theory/page-renderer";
 
-/** The posting's title in `locale`, or `null` when no posting has this slug. */
-export async function postingTitle(slug: string, locale: string): Promise<string | null> {
+/** What an apply page needs from its posting. */
+export interface ApplyPosting {
+  title: string;
+  /** The magnet this posting's apply page runs; absent, the Job application. */
+  applicationFlow?: string;
+}
+
+/** The posting in `locale`, or `null` when no posting has this slug or it has no title. */
+export async function postingForApply(slug: string, locale: string): Promise<ApplyPosting | null> {
   const source = await getMdxSource("JobPosting", slug, locale);
   if (source === null) return null;
-  const title = (source.frontmatter as { title?: unknown }).title;
-  return typeof title === "string" && title.trim() !== "" ? title : null;
+  const { title, applicationFlow } = source.frontmatter as {
+    title?: unknown;
+    applicationFlow?: unknown;
+  };
+  if (typeof title !== "string" || title.trim() === "") return null;
+  return typeof applicationFlow === "string" && applicationFlow !== ""
+    ? { title, applicationFlow }
+    : { title };
+}
+
+/** The posting's title in `locale`, or `null` when no posting has this slug. */
+export async function postingTitle(slug: string, locale: string): Promise<string | null> {
+  return (await postingForApply(slug, locale))?.title ?? null;
 }