@pramen/cms-editor 0.0.60 → 0.0.63

package/src/nav.ts

@@ -31,6 +31,41 @@ export interface ExtraNavLink {
   order?: number;
 }
 
+/** The glyphs the sidebar can draw, by NAME.
+ *
+ * A name, not a component: this module is a pure function of the session's facts and is
+ * tested without a DOM, so it must not import JSX. `NAV_GLYPHS` in `icons.tsx` maps each
+ * name to the drawing, and because this is a closed union a glyph added here without a
+ * drawing is a compile error rather than a blank square in the nav. */
+export type NavGlyph =
+  | "pages"
+  | "collection"
+  | "media"
+  | "menus"
+  | "taxonomies"
+  | "widgets"
+  | "redirects"
+  | "app"
+  | "types"
+  | "users"
+  | "settings"
+  | "link";
+
+/** What sits in an entry's icon slot.
+ *
+ * Two cases because a collection and a Block Kit page may declare their OWN icon
+ * server-side, and that is an arbitrary string (an emoji, in practice). It used to be
+ * prepended to the label — which read as part of the words, wrapped with them, and could
+ * not be aligned with anything. In a sidebar the icon is a column, so a declared emoji goes
+ * in that column and the built-in glyph is the fallback. */
+export type NavIcon = { kind: "glyph"; name: NavGlyph } | { kind: "emoji"; char: string };
+
+/** A server-declared icon if there is one, else the section's own glyph. */
+function iconFor(declared: string | undefined, fallback: NavGlyph): NavIcon {
+  const char = declared?.trim();
+  return char ? { kind: "emoji", char } : { kind: "glyph", name: fallback };
+}
+
 /** One entry in the primary nav.
  *
  * `kind` is what the layout switches on to render it; everything else here is the data it
@@ -38,8 +73,8 @@ export interface ExtraNavLink {
  * buzola page, and the layout is where navigation (and the unsaved-changes guard it runs
  * through) belongs. */
 export type NavEntry =
-  | { kind: "route"; key: string; order: number; label: string; page: NavPage; params?: Record<string, string> }
-  | { kind: "link"; key: string; order: number; link: ExtraNavLink };
+  | { kind: "route"; key: string; order: number; icon: NavIcon; label: string; page: NavPage; params?: Record<string, string> }
+  | { kind: "link"; key: string; order: number; icon: NavIcon; link: ExtraNavLink };
 
 /** What the nav is built from. All of it is already in the app context; passing it in keeps
  * this a pure function of the session's facts. */
@@ -76,10 +111,10 @@ export function buildNav(input: NavInput): NavEntry[] {
       // slug. The label is the type's own `name`, so a host that wants a plural tab writes
       // one.
       for (const t of contentTypes ?? []) {
-        entries.push({ kind: "route", key: `type:${t.slug}`, order: NAV_ORDER.pages, label: t.name, page: "type", params: { slug: t.slug } });
+        entries.push({ kind: "route", key: `type:${t.slug}`, order: NAV_ORDER.pages, icon: { kind: "glyph", name: "pages" }, label: t.name, page: "type", params: { slug: t.slug } });
       }
     } else {
-      entries.push({ kind: "route", key: "pages", order: NAV_ORDER.pages, label: "Pages", page: "home" });
+      entries.push({ kind: "route", key: "pages", order: NAV_ORDER.pages, icon: { kind: "glyph", name: "pages" }, label: "Pages", page: "home" });
     }
   }
 
@@ -88,22 +123,23 @@ export function buildNav(input: NavInput): NavEntry[] {
       kind: "route",
       key: `col:${c.slug}`,
       order: c.navOrder ?? NAV_ORDER.collections,
-      label: `${c.icon ? `${c.icon} ` : ""}${c.pluralLabel}`,
+      icon: iconFor(c.icon, "collection"),
+      label: c.pluralLabel,
       page: "collection",
       params: { slug: c.slug },
     });
   }
 
-  entries.push({ kind: "route", key: "media", order: NAV_ORDER.media, label: "Media", page: "media" });
+  entries.push({ kind: "route", key: "media", order: NAV_ORDER.media, icon: { kind: "glyph", name: "media" }, label: "Media", page: "media" });
 
   if (cms.siteFurniture) {
-    entries.push({ kind: "route", key: "menus", order: NAV_ORDER.menus, label: "Menus", page: "menus" });
+    entries.push({ kind: "route", key: "menus", order: NAV_ORDER.menus, icon: { kind: "glyph", name: "menus" }, label: "Menus", page: "menus" });
     // Taxonomies classify PAGES — `cms_page_terms` links a term to a page and to nothing
     // else — so a collections-only deployment has nothing to classify and the section would
     // be a vocabulary editor with no subject.
-    if (!hidePages) entries.push({ kind: "route", key: "taxonomies", order: NAV_ORDER.taxonomies, label: "Taxonomies", page: "taxonomies" });
-    entries.push({ kind: "route", key: "widgets", order: NAV_ORDER.widgets, label: "Widgets", page: "widgets" });
-    entries.push({ kind: "route", key: "redirects", order: NAV_ORDER.redirects, label: "Redirects", page: "redirects" });
+    if (!hidePages) entries.push({ kind: "route", key: "taxonomies", order: NAV_ORDER.taxonomies, icon: { kind: "glyph", name: "taxonomies" }, label: "Taxonomies", page: "taxonomies" });
+    entries.push({ kind: "route", key: "widgets", order: NAV_ORDER.widgets, icon: { kind: "glyph", name: "widgets" }, label: "Widgets", page: "widgets" });
+    entries.push({ kind: "route", key: "redirects", order: NAV_ORDER.redirects, icon: { kind: "glyph", name: "redirects" }, label: "Redirects", page: "redirects" });
   }
 
   // A project's own screens, INSIDE the chrome and at a position they choose. This is the
@@ -111,24 +147,122 @@ export function buildNav(input: NavInput): NavEntry[] {
   // the odd 10% of a client site was a separate deployment that looked nothing like the
   // admin it hung off.
   for (const p of adminPages) {
-    entries.push({ kind: "route", key: `app:${p.slug}`, order: p.navOrder ?? NAV_ORDER.adminPages, label: `${p.icon ? `${p.icon} ` : ""}${p.label}`, page: "admin-page", params: { slug: p.slug } });
+    entries.push({ kind: "route", key: `app:${p.slug}`, order: p.navOrder ?? NAV_ORDER.adminPages, icon: iconFor(p.icon, "app"), label: p.label, page: "admin-page", params: { slug: p.slug } });
   }
 
   // Authoring the SCHEMA, not content — so it is gated on `canEdit` (every handler behind
   // it is editor-only) and hidden where there is no block/page builder to define types for.
   if (!hidePages && cms.canEdit) {
-    entries.push({ kind: "route", key: "types", order: NAV_ORDER.types, label: "Types", page: "schema" });
+    entries.push({ kind: "route", key: "types", order: NAV_ORDER.types, icon: { kind: "glyph", name: "types" }, label: "Types", page: "schema" });
   }
 
-  if (isAdmin) entries.push({ kind: "route", key: "users", order: NAV_ORDER.users, label: "Users", page: "users" });
-  entries.push({ kind: "route", key: "settings", order: NAV_ORDER.settings, label: "Settings", page: "settings" });
+  if (isAdmin) entries.push({ kind: "route", key: "users", order: NAV_ORDER.users, icon: { kind: "glyph", name: "users" }, label: "Users", page: "users" });
+  entries.push({ kind: "route", key: "settings", order: NAV_ORDER.settings, icon: { kind: "glyph", name: "settings" }, label: "Settings", page: "settings" });
 
   for (const link of extraNav) {
     // Keyed on href AND label: two entries may legitimately point at the same href and
     // differ only in label or target, and keyed on href alone React reconciles them
     // together — the rendered label can end up on the other one's anchor.
-    entries.push({ kind: "link", key: `extra:${link.href}|${link.label}`, order: link.order ?? NAV_ORDER.extra, link });
+    entries.push({ kind: "link", key: `extra:${link.href}|${link.label}`, order: link.order ?? NAV_ORDER.extra, icon: { kind: "glyph", name: "link" }, link });
   }
 
   return entries.sort((a, b) => a.order - b.order);
 }
+
+// --- sections ---------------------------------------------------------------------------
+//
+// Twelve items in one flat list is the thing that stopped being legible — it overran the
+// topbar, and a sidebar alone only turns a crowded row into a long column. So the nav is
+// GROUPED. Grouping rather than hiding: everything a session may reach stays one click away
+// (a submenu costs a click and hides the thing being looked for), and the headings answer
+// "where would I look for this" instead of making the reader scan twelve equal rows.
+//
+// A section is a BAND OF `order`, not a hand-written list of keys. That keeps the one
+// contract this module has — position is a number a host sets (`navOrder` on a collection
+// or an admin page, `order` on an `extraNav` link) — the single thing that decides where an
+// entry appears. A host placing a section at 250 lands in Content, at 450 in Site, exactly
+// as the number reads. Enumerating keys instead would have made a host-placed entry land
+// visually inside a group it was not a member of.
+
+/** A group of nav entries, in order. */
+export type NavSectionId = "content" | "site" | "apps" | "system";
+
+export interface NavSection {
+  id: NavSectionId;
+  /** The heading. Rendered only when there is more than one section — see `navSections`. */
+  label: string;
+  entries: NavEntry[];
+}
+
+/** The bands, in order. `upTo` is EXCLUSIVE, and each is expressed against `NAV_ORDER`
+ * rather than a literal so the two cannot drift: a built-in moving to a new position moves
+ * with its band. */
+const BANDS: readonly { id: NavSectionId; label: string; upTo: number }[] = [
+  // Pages / content types, collections, media — the things an editor came here to write.
+  { id: "content", label: "Content", upTo: NAV_ORDER.menus },
+  // Menus, taxonomies, widget areas, redirects — site-level furniture, not page content.
+  { id: "site", label: "Site", upTo: NAV_ORDER.adminPages },
+  // A project's own Block Kit screens. Their own band rather than a tail of "System",
+  // because they are the project's, and the whole point of `adminPage()` is that they are
+  // not administration of the CMS.
+  { id: "apps", label: "Apps", upTo: NAV_ORDER.types },
+  // Types, users, settings, and host links to companion tools.
+  { id: "system", label: "System", upTo: Number.POSITIVE_INFINITY },
+];
+
+/** Every section id, in rail order. Derived from `BANDS` rather than written out again, so
+ * a new group cannot exist in the layout's eyes but not in the reader's stored folds (or the
+ * reverse). It is what makes a persisted fold PARSEABLE: a value read back out of
+ * localStorage is checked against this, so a stale id from an older version — or anything a
+ * hand-edit put there — is dropped rather than carried into state as "some string". */
+export const NAV_SECTION_IDS: readonly NavSectionId[] = BANDS.map((b) => b.id);
+
+/**
+ * Group the entries `buildNav` returned, dropping empty sections.
+ *
+ * Takes the already-ordered list rather than re-deriving it: the order IS the grouping, so
+ * a second traversal that could disagree with the first would be a bug waiting to happen.
+ * Entries stay in the order they came in, which is what carries the sub-orderings that have
+ * no numeric expression (content-type tabs among themselves, collections sharing a
+ * `navOrder`).
+ */
+export function navSections(entries: NavEntry[]): NavSection[] {
+  const sections: NavSection[] = BANDS.map((b) => ({ id: b.id, label: b.label, entries: [] }));
+  for (const entry of entries) {
+    // The last band is unbounded, so `find` always hits; the `??` is for the type checker.
+    const i = BANDS.findIndex((b) => entry.order < b.upTo);
+    (sections[i === -1 ? sections.length - 1 : i] as NavSection).entries.push(entry);
+  }
+  return sections.filter((s) => s.entries.length > 0);
+}
+
+/**
+ * Should the sections be LABELLED?
+ *
+ * A single heading over the whole nav names nothing — it is a caption on a list with no
+ * sibling to distinguish it from — and a collections-only deployment (`hidePages`, no site
+ * furniture) genuinely is one group. So the headings appear once there are at least two,
+ * and the small deployment keeps a plain list.
+ */
+export function navSectionsAreLabelled(sections: NavSection[]): boolean {
+  return sections.length > 1;
+}
+
+/**
+ * Is the rail ACTUALLY narrowed?
+ *
+ * A named function for `choice && wide`, because conflating those two is what broke it. The
+ * choice is per-browser and persisted; narrowing is expressed entirely in `md:`-scoped
+ * classes, so it only exists at desktop widths. A rail narrowed on a laptop therefore came
+ * back "narrowed" on a phone, where every one of those classes is inert — the rows kept their
+ * labels and their full width, while the JS gated on the stored choice removed all four group
+ * headings, and the hairline that stands in for a heading at 56px is `md:`-only too. One
+ * undifferentiated column of a dozen rows, and the toggle that would undo it is
+ * `hidden md:inline-flex`: no way back from that viewport.
+ *
+ * So JS has to agree with the breakpoint rather than ignore it, and everything conditional —
+ * headings, folding, the hairline — reads this instead of the stored value.
+ */
+export function railIsNarrow(choice: boolean, wideViewport: boolean): boolean {
+  return choice && wideViewport;
+}

package/src/page-header.tsx

@@ -0,0 +1,128 @@
+// The screen header: a cover panel carrying the title and the primary action, which STAYS as
+// the page scrolls.
+//
+// A LEAF module, and it has to be one. `components.tsx` already imports from `furniture.tsx`
+// (for `flattenTerms`), so the two near-identical headers that used to live one in each — a
+// 56px `Hero` and a 40px `Head` — could not be deduplicated by either importing the other
+// without a cycle. Below both, they are one component.
+//
+// ONE type scale, and no `size` prop. The 40px variant was inherited from `Head`: the
+// site-furniture screens (Menus, Taxonomies, Widgets, Redirects) had always been set quieter
+// than the libraries, back when a header was type on the page and the difference read as
+// hierarchy. It does not survive the cover: every screen now gets the same panel with the same
+// generated artwork, so a smaller title on four of them reads as an oversight rather than a
+// rank, and "Navigation" at 40px beside "Media" at 56px is a question a reader has to stop and
+// ask.
+//
+// STICKY, and condensing. The header is the only thing on screen that says which of a dozen
+// interchangeable list screens you are on, and scrolling a media library past the first row
+// used to take it away — leaving a wall of thumbnails with no title and no primary action.
+// Sticky alone would be worse than that: a 190px banner pinned to the top eats a third of the
+// viewport on every scroll. So it condenses — same panel, same artwork, same button, a third
+// of the height — which is the only version of "keep it" that a long list can afford.
+
+import { useEffect, useState, type ReactNode } from "react";
+import { BELOW_APP_BAR } from "./chrome";
+import { CoverArt } from "./cover";
+
+/** TWO thresholds, not one — this is hysteresis, and without it the header flickers.
+ *
+ * Condensing REMOVES about 90px of header, which shortens the document by the same amount. If
+ * the reader is anywhere the browser then has to clamp the scroll offset, `scrollY` moves on
+ * its own — back under a single threshold, which expands the header, which lengthens the
+ * document, which moves `scrollY` again. The state is an input to its own condition, so one
+ * threshold is a feedback loop by construction and no amount of debouncing fixes it: the
+ * oscillation is in the layout, not in the event rate.
+ *
+ * The gap has to exceed the height the switch removes, or the loop simply reappears further
+ * down. `EXPAND_BELOW` is deliberately small so that returning to the top always restores the
+ * full header.
+ */
+const CONDENSE_ABOVE_PX = 120;
+const EXPAND_BELOW_PX = 16;
+
+/**
+ * Has the page scrolled far enough to condense the header?
+ *
+ * On `window`, because the editor's shell deliberately keeps the DOCUMENT as its scroller (the
+ * rail is a sticky grid column, not an inner scroll pane) — so this is the one scroll position
+ * there is. `passive` since nothing here can cancel the scroll, and React bails out of a
+ * re-render when the value is unchanged, so a scroll inside the dead band costs a comparison.
+ */
+function useCondensed(): boolean {
+  const [condensed, setCondensed] = useState(false);
+  useEffect(() => {
+    // Reads the CURRENT value rather than closing over it, so the listener is registered once
+    // and the dead band is evaluated against what is actually on screen.
+    const onScroll = (): void =>
+      setCondensed((was) => (was ? window.scrollY > EXPAND_BELOW_PX : window.scrollY > CONDENSE_ABOVE_PX));
+    onScroll(); // a deep link can land already scrolled (browser scroll restoration)
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => window.removeEventListener("scroll", onScroll);
+  }, []);
+  return condensed;
+}
+
+/**
+ * The header.
+ *
+ * Seeded on `lead`, NOT on `em`. `lead` is the screen's name ("Media", a collection's plural
+ * label) and `em` is its state ("None yet", "3 files") — seeding on what is displayed would
+ * redraw the artwork every time someone uploaded a file, which is the one thing a picture
+ * meant to make a screen RECOGNISABLE must never do.
+ *
+ * The mask over the art is a hard requirement, not polish: the title is large and set left, and
+ * `from-surface-card` fading to transparent is what guarantees it never lands on pattern
+ * whatever the seed produced. The `via` stop is the whole tuning knob — at `/85` the middle of
+ * the panel is still 85% panel colour and the artwork only ever appears in the last third,
+ * which is a cover you cannot see; `/70` clears the type (which ends around 26% of the width)
+ * and lets the field read across the rest.
+ */
+export function PageHeader({ lead, em, children }: { lead: string; em: string; children?: ReactNode }) {
+  const condensed = useCondensed();
+  return (
+    // The GUTTER is what sticks, not the panel: pinning the panel alone would let rows scroll
+    // through the 28px of page margin either side of it and out the rounded corners. `bg-surface`
+    // on this wrapper is therefore load-bearing, not decoration.
+    //
+    // NO padding above: the panel meets the app bar directly, so the two read as one block of
+    // chrome rather than a bar with a panel parked under it. That also leaves nothing on this
+    // wrapper that changes between the two states, which is why the collapse transition lives
+    // only on the panel below — a transition on an element whose padding is constant is dead
+    // code that looks load-bearing.
+    //
+    // `z-20` sits above the list and below the rail's mobile disclosure (which is in flow above
+    // it) and every modal overlay (z-50).
+    <div className={`sticky ${BELOW_APP_BAR} z-20 mx-auto max-w-[1200px] bg-surface px-7 pb-4`}>
+      <div className="relative isolate overflow-hidden rounded-panel border border-border bg-surface-card">
+        <CoverArt seed={lead} />
+        <div className="absolute inset-0 bg-gradient-to-r from-surface-card via-surface-card/70 to-transparent" />
+        <div
+          className={`relative grid grid-cols-[1fr_auto] items-center gap-6 px-8 transition-[padding] duration-150 ease-out max-[820px]:grid-cols-1 ${
+            condensed ? "py-3.5" : "py-9"
+          }`}
+        >
+          {/* Condensed, the two halves run on ONE line. Stacked they would keep the full
+              header's height and defeat the point; and the title has to stay a single `<h1>`
+              across the switch, or a screen reader is handed a new heading every time the
+              reader scrolls. */}
+          <h1
+            // NO transition on the type. `transition-all` here animated `font-size` 56px -> 22px,
+            // which relayouts the panel on every frame of the tween — on a STICKY element whose
+            // height feeds back into the scroll position, which is the other half of the flicker.
+            // And `display` (two stacked lines -> one baseline row) cannot be tweened at all, so
+            // the line count snapped mid-animation regardless. The type switches at once; the
+            // padding below carries the motion.
+            className={`m-0 font-normal tracking-[-0.01em] ${
+              condensed ? "flex items-baseline gap-2 text-[22px] leading-tight" : "text-[56px] leading-[1.05] max-[820px]:text-[40px]"
+            }`}
+          >
+            <span className={condensed ? "text-fg-subtle" : "block text-fg-subtle"}>{lead}</span>
+            <span className={condensed ? "text-fg" : "block text-fg"}>{em}</span>
+          </h1>
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/preview.ts

@@ -0,0 +1,65 @@
+// Where a minted preview token is redeemed.
+//
+// A LEAF module, like `chrome.ts`: the page editor and the collection editor both mint
+// links, and the rule for turning a mint into an href has to be one rule.
+//
+// The CMS is headless. `signPagePreview` returns a token plus a relative url that the CMS
+// Worker redeems itself — and that endpoint answers with JSON, because the server has the
+// draft and no idea what it should look like. That is the right default for a machine and
+// the wrong one for the person preview exists for: a stakeholder without an account, sent a
+// link, who opens a wall of braces.
+//
+// So a host may declare where ITS OWN site renders a preview. Same seam as `menuHref` and
+// the sitemap's `pageUrl` — the CMS cannot know how a deployment routes, so the deployment
+// says. Unset, nothing changes: the link still points at the backend.
+
+/** What the host may set under `window.PRAMEN_CMS_EDITOR.previewUrl`. */
+interface PreviewHost {
+  PRAMEN_CMS_EDITOR?: { previewUrl?: unknown };
+}
+
+/** The site's own preview route, if the shell declared a usable one.
+ *
+ * Anything that is not a non-empty string is ignored rather than coerced — a `previewUrl`
+ * of `true` or `0` would otherwise build a link to `"true?token=…"`, which fails as a
+ * broken page rather than as a configuration error anyone can see. */
+export function sitePreviewUrl(host: PreviewHost = globalThis as PreviewHost): string | undefined {
+  const raw = host.PRAMEN_CMS_EDITOR?.previewUrl;
+  if (typeof raw !== "string") return undefined;
+  const trimmed = raw.trim();
+  return trimmed === "" ? undefined : trimmed;
+}
+
+/** Build the href for a minted PAGE preview. ALWAYS ABSOLUTE.
+ *
+ * `resolve` is the fallback: the backend-relative url the mint returned, made absolute
+ * against the CMS origin — exactly what this did before a site route could be declared.
+ *
+ * Absolute because the result is not only navigated to, it is COPIED and shown: half the
+ * reason the button exists is to send the link to someone who has no account. `previewUrl` is
+ * normally written as a path (`"/preview"`), so the configured — recommended — path was the
+ * one that produced `/preview?token=…` in the clipboard: dead the moment it is pasted into
+ * Slack. The new tab hid it, because a blank window opened by this document inherits its base
+ * URL and resolves the relative href perfectly well.
+ *
+ * `origin` is passed rather than read from `location` so this stays a pure function that can
+ * be tested; an already-absolute `siteUrl` is left alone by `new URL`. */
+export function pagePreviewHref(
+  minted: { url: string; token: string },
+  opts: { siteUrl?: string; origin: string; resolve: (path: string) => string },
+): string {
+  const site = opts.siteUrl;
+  if (!site) return opts.resolve(minted.url);
+  // The declared route may already carry query params (a locale, a layout switch), so the
+  // separator is decided rather than assumed — `?` twice is a link that silently drops the
+  // token into a parameter name.
+  const sep = site.includes("?") ? "&" : "?";
+  const href = `${site}${sep}token=${encodeURIComponent(minted.token)}`;
+  try {
+    return new URL(href, opts.origin).href;
+  } catch {
+    // An unparseable origin (or a `previewUrl` that is not a URL at all) must not throw in
+    // the middle of minting — the relative href is what this returned before and still opens.
+    return href;
+  }
+}