@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/nav.ts

@@ -0,0 +1,176 @@
+import type { PageDeclaration } from './contract'
+
+/**
+ * Deriving a site's page declarations from the navigation it already has.
+ *
+ * A site's information architecture is already written down — it is the header nav, and
+ * usually a `brand.ts` array of `{ label, href, items }`. Asking a site to *also* hand-write
+ * a flat list of `{ label, slug, parent }` for the manifest would be asking it to maintain
+ * the same tree twice, and the copy the platform reads would be the one that goes stale.
+ * JDSi's nav is forty routes deep in three levels; nobody is keeping a second copy of that
+ * correct by hand.
+ *
+ * So the manifest's `pages` is generated from the nav, and the nav stays the single place a
+ * route is added. What this file does is entirely mechanical — flatten, resolve, dedupe —
+ * and every rule below exists because a real nav has entries in it that are not pages.
+ */
+
+/**
+ * A nav entry, as loosely as a site is likely to have written one.
+ *
+ * Every field optional and unknown keys allowed on purpose: a real nav carries `blurb`,
+ * `image`, `external` and whatever else its own menu renders, and a site should be able to
+ * pass `brand.nav` straight in without reshaping it. Anything not named here is ignored.
+ */
+export type NavEntry = {
+  href?: null | string
+  items?: readonly NavEntry[]
+  label?: string
+}
+
+/**
+ * The shape the platform accepts for a page slug.
+ *
+ * A deliberate duplicate of `PAGE_SLUG` in the platform's `manifest/validate.ts`, which is
+ * the authority. It is repeated here because of what happens when the two disagree: **one bad
+ * slug rejects the entire manifest**, taking the tenant's blocks and their whole editor with
+ * it, and disqualifying the cached fallback because an invalid manifest is not "the site is
+ * unreachable". A helper that is the documented way to produce `pages` must not be able to do
+ * that to the site that uses it.
+ */
+const PAGE_SLUG = /^[a-z0-9]+(?:[/-][a-z0-9]+)*$/
+
+/**
+ * A nav href as a page slug, or null when the entry is not a page of its own.
+ *
+ * Five things get rejected, and each one is in a real nav:
+ *
+ *  - **A fragment link.** `/careers#how-to-apply` is a position on the careers page, not a
+ *    page. Listed as one it would appear in the sitemap as a page with no content that can
+ *    never be published, and "add a page here" would offer to create a route the site does
+ *    not serve.
+ *  - **An external link.** `https://linkedin.com/…` is not this site's to route.
+ *  - **A group with no href.** A label that only opens a submenu is a menu affordance; its
+ *    children belong to whatever the group itself sits under.
+ *  - **A query string.** Same route, different state.
+ *  - **Anything still not slug-shaped** after normalising — an underscore, an ampersand, an
+ *    encoded character, a space. Dropped rather than emitted, because emitting it would take
+ *    down the whole manifest (see `PAGE_SLUG`), and because a route the platform cannot name
+ *    is one it could not offer to edit anyway. The site keeps serving it either way; it
+ *    simply does not appear on the client's map.
+ *
+ * Case and repeated slashes are *normalised* rather than rejected, since `/About-Us` and
+ * `/about//us` name routes the platform can perfectly well express and a site that writes
+ * either meant the ordinary thing.
+ */
+const slugFromHref = (href: null | string | undefined): null | string => {
+  if (typeof href !== 'string') return null
+
+  const trimmed = href.trim()
+  if (trimmed.length === 0) return null
+  // `//host` is protocol-relative and therefore external, despite starting with a slash.
+  if (trimmed.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(trimmed)) return null
+  if (!trimmed.startsWith('/')) return null
+  if (trimmed.includes('#') || trimmed.includes('?')) return null
+
+  const slug = trimmed
+    .toLowerCase()
+    // `/about//us` and `/about/us/` are the same route as `/about/us`.
+    .replace(/\/+/g, '/')
+    .replace(/^\/+/, '')
+    .replace(/\/+$/, '')
+
+  /*
+   * The landing page is `home`, not the empty string.
+   *
+   * That is the slug the platform's own page documents use for it — the `pages` collection
+   * describes it as such and every site's seed is written against it — so emitting `''`
+   * here would produce a landing page that never matched the document holding its content.
+   */
+  if (slug.length === 0) return 'home'
+
+  return PAGE_SLUG.test(slug) ? slug : null
+}
+
+/**
+ * Flatten a nav tree into the page declarations a manifest publishes.
+ *
+ * Pass the nav with the landing page in front of it, which is the whole call:
+ *
+ * ```ts
+ * export const pages = pagesFromNav([
+ *   { label: 'Home', href: '/' },
+ *   ...brand.nav,
+ *   ...brand.navUtility,
+ * ])
+ * ```
+ *
+ * Structure is preserved: an entry's `items` become its children, so the platform's sitemap
+ * is the menu the visitor sees. Order is preserved too — the manifest's order is the order
+ * the sitemap draws, and nav order is the site's own considered answer to what comes first.
+ *
+ * **A slug appears once, at the shallowest place the nav mentions it.** Nav trees repeat
+ * themselves constantly: every JDSi submenu opens with an "Overview" pointing back at the
+ * section landing page it hangs under, and `/resources` appears in the header, in a hero slide
+ * and in a footer column. Deduping means a site can concatenate every list of links it has
+ * without producing a sitemap with four "Overview" nodes under each section.
+ *
+ * *Shallowest* rather than first, so the result does not depend on the order a site happens to
+ * concatenate its lists in. A page cross-linked from deep inside one section and also present
+ * as a section of its own belongs at the top level — first-occurrence would have filed
+ * "Work With Us" under "Who We Are" purely because a link to it appeared there first, and
+ * reordering a footer column would silently reshape the client's map. At equal depth the first
+ * still wins, and the shallowest mention is also the one carrying the real label — the deeper
+ * repeat is the one called "Overview".
+ */
+export const pagesFromNav = (nav: readonly NavEntry[]): PageDeclaration[] => {
+  /** Insertion-ordered, so declaration order stays nav order. Depth is kept to compare repeats. */
+  const found = new Map<string, { depth: number; page: PageDeclaration }>()
+
+  const walk = (entries: readonly NavEntry[], parent: string | undefined, depth: number): void => {
+    for (const entry of entries) {
+      if (!entry || typeof entry !== 'object') continue
+
+      const slug = slugFromHref(entry.href)
+
+      /*
+       * A group with no page of its own passes its parent down rather than becoming one.
+       *
+       * Without this its children would be orphaned to the top level, and a nav that groups
+       * "Services" purely as a heading would flatten every service into a root page. Its
+       * depth is not spent either — the children sit where the group sits.
+       */
+      const inherited = slug === null ? parent : slug
+
+      if (slug !== null) {
+        const existing = found.get(slug)
+
+        if (!existing || depth < existing.depth) {
+          const page: PageDeclaration = {
+            label:
+              typeof entry.label === 'string' && entry.label.trim().length > 0
+                ? entry.label.trim()
+                : slug,
+            // Omitted rather than undefined-valued, so the emitted JSON has no null parents.
+            ...(parent === undefined || parent === slug ? {} : { parent }),
+            slug,
+          }
+          /*
+           * `set` on an existing key keeps its original position in the Map, which is what
+           * should happen: a shallower mention corrects a page's *parent and label*, not the
+           * order its section reads in.
+           */
+          found.set(slug, { depth, page })
+        }
+      }
+
+      if (Array.isArray(entry.items) && entry.items.length > 0) {
+        walk(entry.items, inherited, slug === null ? depth : depth + 1)
+      }
+    }
+  }
+
+  walk(nav, undefined, 0)
+
+  return [...found.values()].map((entry) => entry.page)
+}

package/src/legacy/preview.ts

@@ -0,0 +1,79 @@
+/**
+ * How long a preview lasts, and what says so.
+ *
+ * Draft mode is two cookies — Next's own `__prerender_bypass` and the `payload-token`
+ * this kit stashes — and both are *session* cookies with no expiry. `createExitPreviewRoute`
+ * clears them, and `DraftNotice` offers the link that calls it, but both of those need
+ * somebody to click. Nothing clicks on behalf of a browser whose tab was closed, whose
+ * machine slept, or which was framed inside Canvas — where the notice deliberately hides
+ * itself, so the exit is not on offer at all.
+ *
+ * The consequence is not theoretical. A browser left in draft mode reads staged content on
+ * every page of the site, forever: modern browsers restore sessions rather than ending
+ * them, so "until it is quit" never arrives. Once the staged content it is reading is
+ * discarded or its token goes stale, that one browser sees a broken or empty version of a
+ * site which is perfectly healthy for everybody else — including, when it is the client's
+ * browser, on their own live domain.
+ *
+ * So the window is stamped into a cookie of our own and checked on read. A preview that
+ * nobody exits now lapses on its own, and the failure mode is the safe direction: the
+ * published site, which is what a visitor sees anyway.
+ */
+
+/** Next's token, stashed so a preview reads drafts as the signed-in client. */
+export const PREVIEW_TOKEN_COOKIE = 'payload-token'
+
+/** When the current preview stops counting, as epoch milliseconds in a cookie. */
+export const PREVIEW_UNTIL_COOKIE = 'u90-preview-until'
+
+/**
+ * Long enough for a working session, short enough that a forgotten tab heals by morning.
+ *
+ * Erring long is the wrong way to err: the cost of a window that is too short is one
+ * re-click of Preview, and the cost of one that is too long is the failure above.
+ */
+export const PREVIEW_MAX_AGE_SECONDS = 8 * 60 * 60
+
+/**
+ * Whether a stamp means "no longer previewing".
+ *
+ * A missing stamp counts as closed, which is what makes this self-healing: a browser that
+ * entered draft mode before this existed has no stamp, so the first request after the
+ * deploy puts it back on the published site without anyone knowing to clear anything.
+ * Unparseable counts as closed for the same reason — the only value worth trusting is a
+ * deadline we can actually read, still in the future.
+ */
+export const previewWindowClosed = (stamp: undefined | string, now = Date.now()): boolean => {
+  if (!stamp) return true
+  const deadline = Number(stamp)
+  return !Number.isFinite(deadline) || deadline <= now
+}
+
+/** One frame's locale and generation. Revision changes when its locale/context is replaced. */
+export type LanguageFrameContext = { locale: string; revision: number }
+export function acceptsLanguageFrame(
+  context: LanguageFrameContext | undefined,
+  message: Record<string, unknown>,
+): boolean {
+  return (
+    !context || (message.locale === context.locale && message.languageRevision === context.revision)
+  )
+}
+
+/** Preserve a preview artboard's generation through same-origin site navigation. */
+export function languageFrameNavigation(
+  href: string,
+  base: string,
+  context: LanguageFrameContext | undefined,
+): string | null {
+  if (!context) return null
+  try {
+    const target = new URL(href, base)
+    if (target.origin !== new URL(base).origin || !['http:', 'https:'].includes(target.protocol))
+      return null
+    target.searchParams.set('languageRevision', String(context.revision))
+    return target.href
+  } catch {
+    return null
+  }
+}