@drawnagency/primitives 0.1.98 → 0.1.100

package/src/components/docfile/doc-file-state.ts

@@ -0,0 +1,180 @@
+import type { SiteDocument } from "../../lib/documents";
+import { createEvent } from "../../lib/events";
+
+/** Toggled on <html> while a document is open (the chat's class mechanism). */
+export const DOC_OPEN_CLASS = "bp-doc-open";
+
+/** The one breakpoint the doc feature keys off: at or above it the overlay
+ *  gets the desktop stage; below it a PDF goes to the OS viewer instead (iOS
+ *  Safari cannot scroll an iframed PDF, Android Chrome forces a download).
+ *  1024px — the SAME breakpoint as U5's desktop CSS block and the width where
+ *  the nav sidebar exists at all. Deliberately NOT the chat's 768px dock query:
+ *  keying JS at 768 while the pane's desktop rules start at 1024 would give
+ *  768–1023px viewers framed PDFs inside the mobile pane geometry, under a
+ *  docked chat. */
+export const DOC_DESKTOP_QUERY = "(min-width: 1024px)";
+
+/** Cross-island open request. Islands that would rather not import this module
+ *  can dispatch it instead; applying an already-current value is a no-op, so
+ *  the dispatch-listen pair cannot loop. */
+export const docFileOpenEvent = createEvent<{ sectionId: string | null }>("bp-doc-file-open");
+
+interface DocFileStore {
+  open: string | null;
+  /** null = not seeded yet. Distinct from [] (seeded, no documents) — a row
+   *  that hydrates before the overlay must not flash "file missing". */
+  docs: SiteDocument[] | null;
+  openListeners: Set<(id: string | null) => void>;
+  docsListeners: Set<(docs: SiteDocument[] | null) => void>;
+  teardown: (() => void) | null;
+}
+
+// Symbol-keyed on globalThis for the same reason the section registry is: the
+// bundler may hand two islands two copies of this module, and a split store
+// would let the nav open a document the overlay never hears about.
+const STORE_KEY = Symbol.for("@drawnagency/primitives/doc-file-state");
+const g = globalThis as unknown as Record<symbol, DocFileStore | undefined>;
+
+function store(): DocFileStore {
+  let s = g[STORE_KEY];
+  if (!s) {
+    s = { open: null, docs: null, openListeners: new Set(), docsListeners: new Set(), teardown: null };
+    g[STORE_KEY] = s;
+  }
+  return s;
+}
+
+export function isDocDesktop(): boolean {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return true;
+  return window.matchMedia(DOC_DESKTOP_QUERY).matches;
+}
+
+function readHash(): string | null {
+  if (typeof window === "undefined") return null;
+  const match = /^#doc=(.+)$/.exec(window.location.hash);
+  if (!match) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return match[1];
+  }
+}
+
+function apply(sectionId: string | null): void {
+  const s = store();
+  if (s.open === sectionId) return;
+  s.open = sectionId;
+  if (typeof document !== "undefined") {
+    document.documentElement.classList.toggle(DOC_OPEN_CLASS, sectionId !== null);
+  }
+  for (const listener of [...s.openListeners]) listener(sectionId);
+}
+
+function syncFromHash(): void {
+  const next = readHash();
+  // "Ignores hash writes that still contain its own value" — a same-value
+  // write (e.g. a repeated nav click on the already-open document) must not
+  // re-notify. NOTE the one hash writer that CAN silently stomp #doc is a nav
+  // HEADING click (useActiveHeadings' setActiveSection does a replaceState —
+  // click-driven, not scroll-driven, so the scroll lock does not prevent it);
+  // U3 closes the overlay in handleHeadingNav before that write happens.
+  if (next === store().open) return;
+  apply(next);
+}
+
+export function openDocFile(sectionId: string): void {
+  if (typeof window !== "undefined") {
+    const hash = `#doc=${encodeURIComponent(sectionId)}`;
+    if (window.location.hash !== hash) {
+      // pushState so Back closes the overlay. It fires no hashchange, which is
+      // why the atom — not the hash — is the store.
+      window.history.pushState(null, "", hash);
+    }
+  }
+  apply(sectionId);
+  docFileOpenEvent.dispatch({ sectionId });
+}
+
+export function closeDocFile(): void {
+  if (typeof window !== "undefined" && readHash() !== null) {
+    // replaceState, never history.back(): back() races the editor's own
+    // pushState in goToPage and is unobservable in jsdom. The cost is that Back
+    // after a manual close returns to an identical URL — invisible to the user.
+    const { pathname, search } = window.location;
+    window.history.replaceState(null, "", `${pathname}${search}`);
+  }
+  apply(null);
+  docFileOpenEvent.dispatch({ sectionId: null });
+}
+
+export function getOpenDocFile(): string | null {
+  return store().open;
+}
+
+export function subscribeDocFile(cb: (sectionId: string | null) => void): () => void {
+  const s = store();
+  s.openListeners.add(cb);
+  if (!s.teardown && typeof window !== "undefined") {
+    const onHash = () => syncFromHash();
+    const onPop = () => syncFromHash();
+    const onRequest = (detail: { sectionId: string | null }) => {
+      // The already-current check must come FIRST and cover null too: this
+      // listener also hears the event openDocFile/closeDocFile dispatch
+      // themselves, and an unguarded close would re-close → re-dispatch →
+      // recurse until the stack blew (jsdom swallows listener throws, so the
+      // suite only surfaced it as an unhandled RangeError).
+      if (detail.sectionId === s.open) return;
+      if (detail.sectionId === null) closeDocFile();
+      else openDocFile(detail.sectionId);
+    };
+    window.addEventListener("hashchange", onHash);
+    window.addEventListener("popstate", onPop);
+    const unlistenRequest = docFileOpenEvent.listen(onRequest);
+    s.teardown = () => {
+      window.removeEventListener("hashchange", onHash);
+      window.removeEventListener("popstate", onPop);
+      unlistenRequest();
+    };
+    // Deep link: the hash is an INPUT, read once when the first listener wires up.
+    syncFromHash();
+  }
+  return () => {
+    s.openListeners.delete(cb);
+    if (s.openListeners.size === 0 && s.teardown) {
+      s.teardown();
+      s.teardown = null;
+    }
+  };
+}
+
+/** Authoritative publish — the editor's live draft list. */
+export function setSiteDocuments(docs: SiteDocument[]): void {
+  const s = store();
+  s.docs = docs;
+  for (const listener of [...s.docsListeners]) listener(docs);
+}
+
+/** First-writer-wins publish for the SSR-derived list, so an island that mounts
+ *  after the editor has already published cannot clobber the live list. */
+export function seedSiteDocuments(docs: SiteDocument[]): void {
+  if (store().docs !== null) return;
+  setSiteDocuments(docs);
+}
+
+export function getSiteDocuments(): SiteDocument[] | null {
+  return store().docs;
+}
+
+export function subscribeSiteDocuments(cb: (docs: SiteDocument[] | null) => void): () => void {
+  const s = store();
+  s.docsListeners.add(cb);
+  return () => { s.docsListeners.delete(cb); };
+}
+
+/** Test-only: drop the store and any window wiring (mirrors clearRegistry). */
+export function resetDocFileState(): void {
+  const s = g[STORE_KEY];
+  if (s?.teardown) s.teardown();
+  if (typeof document !== "undefined") document.documentElement.classList.remove(DOC_OPEN_CLASS);
+  g[STORE_KEY] = undefined;
+}

package/src/components/editor/SettingsForm.tsx

@@ -6,6 +6,7 @@ import { Checkbox } from "../shared/Checkbox";
 import { FormLabel } from "../shared/FormLabel";
 import { LinkField } from "../shared/LinkField";
 import { VideoSourceField } from "../shared/VideoSourceField";
+import { DocumentSourceField, type DocumentRef } from "../shared/DocumentSourceField";
 import { Tabs } from "../shared/Tabs";
 import type { LinkValue } from "../../schemas/link";
 import type { VideoSource } from "../sections/Video/VideoBlock";
@@ -174,6 +175,15 @@ function renderField(
         />
       );
 
+    case "document-source":
+      return (
+        <DocumentSourceField
+          key={key}
+          value={value as DocumentRef | undefined}
+          onChange={(v) => handleFieldChange(key, v)}
+        />
+      );
+
     default:
       return null;
   }

package/src/components/sections/Document/index.tsx

@@ -0,0 +1,163 @@
+import { useEffect, useState } from "react";
+import { z } from "zod";
+import { ExternalLink, FileText } from "lucide-react";
+import { defineSection } from "../../../lib/registry";
+import { cn } from "../../../lib/cn";
+import { formatDocSize, type SiteDocument } from "../../../lib/documents";
+import {
+  getSiteDocuments,
+  subscribeSiteDocuments,
+  openDocFile,
+  isDocDesktop,
+} from "../../docfile/doc-file-state";
+
+const schema = z.object({
+  type: z.literal("document"),
+  content: z.object({
+    title: z
+      .string()
+      .describe("Row title. Leave it blank to show the file name without its extension; type a title to override that."),
+    doc: z.object({
+      documentId: z
+        .string()
+        .default("")
+        .describe(
+          "Hash key into the document manifest (src/content/document-manifest.json). Deliberately NOT `imageId`: documents are not resolved by the media ref-baker.",
+        ),
+    }),
+    showInDocumentsNav: z
+      .boolean()
+      .default(true)
+      .describe(
+        "When true, this document also appears in the auto-derived Documents group at the bottom of the left navigation, openable from any page.",
+      ),
+  }),
+  options: z.object({}).default({}),
+});
+
+/** Subscribes to the site-wide document list published by the DocFileOverlay
+ *  island (viewer: SSR-derived; editor: live from EditorShell). `null` means
+ *  "not seeded yet" — distinct from "seeded, and this id isn't in it", which is
+ *  the missing-file state. */
+function useSiteDocument(sectionId: string): { doc: SiteDocument | null; resolved: boolean } {
+  const [docs, setDocs] = useState<SiteDocument[] | null>(null);
+  useEffect(() => {
+    setDocs(getSiteDocuments());
+    return subscribeSiteDocuments(setDocs);
+  }, []);
+  return {
+    doc: docs ? (docs.find((d) => d.sectionId === sectionId) ?? null) : null,
+    resolved: docs !== null,
+  };
+}
+
+export function DocumentRow({
+  sectionId,
+  title,
+  isEditMode,
+}: {
+  sectionId: string;
+  title: string;
+  isEditMode: boolean;
+}) {
+  const { doc, resolved } = useSiteDocument(sectionId);
+
+  // Viewers never see a row whose bytes are gone — deriveSiteDocuments already
+  // dropped it, so absence here is authoritative. Editors keep a muted row so
+  // the section stays selectable and repairable.
+  if (resolved && !doc && !isEditMode) return null;
+
+  // `doc.title` is already `content.title || filenameStem(entry.filename)` —
+  // deriveSiteDocuments applies the fallback once so the row, the Documents nav
+  // entry and the overlay top bar can never disagree. Picking a file NEVER
+  // writes `title` (reconciliation decision 6). `title` (raw section content)
+  // is only the pre-seed placeholder, before the registry has published.
+  const label = doc?.title ?? title;
+
+  function handleClick() {
+    if (!doc) return;
+    // iOS Safari cannot scroll an iframed PDF and Android Chrome forces a
+    // download — hand phones the OS viewer instead. HTML still uses the overlay.
+    if (doc.kind === "pdf" && !isDocDesktop()) {
+      window.open(doc.url, "_blank", "noopener,noreferrer");
+      return;
+    }
+    openDocFile(sectionId);
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={!doc}
+      aria-label={doc ? `Open ${label}` : undefined}
+      className={cn(
+        "flex w-full min-w-0 items-center gap-3 rounded-outer border border-base-200 bg-base px-4 py-3 text-left transition-colors",
+        doc ? "cursor-pointer hover:bg-base-accent" : "cursor-default opacity-60",
+      )}
+    >
+      <FileText size={18} aria-hidden="true" className="shrink-0 text-base-contrast/60" />
+      <div className="min-w-0 flex-1">
+        <div className="flex items-center gap-2">
+          <span className="truncate text-sm font-medium text-base-contrast">{label}</span>
+          {doc && (
+            <span className="shrink-0 rounded bg-base-100 px-1.5 py-0.5 text-xs font-medium text-base-contrast">
+              {doc.kind === "pdf" ? "PDF" : "HTML"}
+            </span>
+          )}
+        </div>
+        <div className="truncate text-xs text-base-contrast/70">
+          {doc ? `${doc.filename} · ${formatDocSize(doc.size)}` : resolved ? "File missing" : "\u00a0"}
+        </div>
+      </div>
+      {doc && <ExternalLink size={16} aria-hidden="true" className="shrink-0 text-base-contrast/50" />}
+    </button>
+  );
+}
+
+export default defineSection({
+  type: "document",
+  category: "brand-guide",
+  label: "Document",
+  icon: <FileText size={18} />,
+  schema,
+  // The row reads the client-side document registry and opens the overlay, so
+  // the viewer hydrates it as an island rather than emitting static HTML.
+  interactive: true,
+  authoringNote:
+    "One downloadable/viewable file — a PDF or a single self-contained HTML file — presented as a clickable row. " +
+    "Clicking opens it in a full-viewport preview overlay without leaving the page; on phones a PDF opens in the OS viewer instead. " +
+    "Pick the file from the media library (documents tab); leave the title blank to show the file name without its extension, or type one to override it. " +
+    "Leave 'Show in Documents menu' on for anything a viewer should be able to reach from any page — those entries collect into a derived Documents group at the bottom of the left nav. " +
+    "Use one section per file; for a set of downloads, place several document sections in a container.",
+  component: ({ content, isEditMode }) => (
+    <DocumentRow
+      // The section id is added by the outer Section schema (id + layout
+      // intersected with the per-type schema), so it is present at render time
+      // but absent from this type's inferred content shape.
+      sectionId={(content as unknown as { id?: string }).id ?? ""}
+      title={content.content.title}
+      isEditMode={isEditMode}
+    />
+  ),
+  defaults: () => ({
+    type: "document" as const,
+    content: { title: "", doc: { documentId: "" }, showInDocumentsNav: true },
+    options: {},
+  }),
+  getLabel: (content) => content.content.title || "Document",
+  settings: {
+    doc: { type: "document-source", label: "File", target: "content", default: { documentId: "" } },
+    title: { type: "text", label: "Title", target: "content", default: "", placeholder: "Document title" },
+    showInDocumentsNav: {
+      type: "checkbox",
+      label: "Show in Documents menu",
+      target: "content",
+      default: true,
+    },
+  },
+  settingsTabs: [
+    { label: "File", fields: ["doc", "title"] },
+    { label: "Display", fields: ["showInDocumentsNav"] },
+  ],
+});

package/src/components/sections/brand-guide.ts

@@ -1,13 +1,14 @@
 import colors from "./Colors";
 import iconList from "./IconList";
 import doDontMedia from "./DoDontMedia";
+import documentSection from "./Document";
 
 /** Opinionated brand-guide sections. Self-contained subtree: a build that does
  *  not import this module drops these sections (and their cmyk/pantone schemas
  *  and do/dont compositions) entirely. Exposed at
  *  `@drawnagency/primitives/components/sections/brand-guide`. */
 // Un-annotated for the same generic-variance reason as coreSectionDefs.
-export const brandGuideSectionDefs = [colors, iconList, doDontMedia];
+export const brandGuideSectionDefs = [colors, iconList, doDontMedia, documentSection];
 
 export { ColorSpaceSchema, ColorItemSchema } from "./Colors/schema";
 export type { ColorSpace, ColorItem } from "./Colors/schema";

package/src/components/shared/DocumentSourceField.tsx

@@ -0,0 +1,51 @@
+import { FormLabel } from "./FormLabel";
+import { Button } from "./Button";
+import { useMediaLibrary } from "../shell/MediaLibraryContext";
+import { useResolvedDocument } from "../../hooks/useResolvedDocument";
+import { formatFileSize } from "../../media/utils";
+
+export interface DocumentRef {
+  documentId: string;
+}
+
+interface Props {
+  value: DocumentRef | undefined;
+  onChange: (value: DocumentRef) => void;
+}
+
+/** Picker for the `document` section type. Writes only { documentId } — the
+ *  filename/size shown here are read back out of the sidecar manifest, never
+ *  copied into section content. */
+export function DocumentSourceField({ value, onChange }: Props) {
+  const mediaLibrary = useMediaLibrary();
+  const documentId = value?.documentId || undefined;
+  const { entry, missing } = useResolvedDocument(documentId);
+
+  return (
+    <div className="flex flex-col gap-3">
+      <FormLabel>Document</FormLabel>
+      <div className="flex items-center gap-3">
+        {entry ? (
+          <span className="min-w-0 flex-1 truncate text-sm text-base-contrast">
+            {entry.filename}
+            <span className="text-base-contrast-light"> · {formatFileSize(entry.size)}</span>
+          </span>
+        ) : (
+          <span className="flex-1 text-sm text-base-contrast-light">
+            {missing ? "File missing" : "No document selected"}
+          </span>
+        )}
+        <Button
+          type="button"
+          variant="secondary"
+          size="sm"
+          onClick={() =>
+            mediaLibrary?.openSelectModal((id) => onChange({ documentId: id }), { kinds: ["document"] })
+          }
+        >
+          {documentId ? "Replace document" : "Choose document"}
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/components/shared/Navigation.tsx

@@ -1,9 +1,10 @@
-import { useState, useCallback, useEffect, useRef } from "react";
+import { useState, useCallback, useEffect, useRef, type ReactNode } from "react";
 import { ChevronRight } from "lucide-react";
 import { cn } from "../../lib/cn";
 import { Toggle } from "./Toggle";
-import type { SiteNav, NavItem, GroupNavItem, PageNavItem } from "../../lib/nav";
+import type { SiteNav, NavItem, GroupNavItem, PageNavItem, DocGroupNavItem, DocNavItem } from "../../lib/nav";
 import { groupDisplayLabel } from "../../lib/nav-tree";
+import { openDocFile, closeDocFile } from "../docfile/doc-file-state";
 import { editModeEvent, siteNavChangeEvent, pageSelectEvent, darkModeEvent, siteNameChangeEvent, historySelectEvent, editorDirtyEvent } from "../../lib/events";
 import { useActiveHeadings } from "../../hooks/useActiveHeadings";
 import { formatDate } from "../../lib/timestamp";
@@ -81,7 +82,9 @@ export default function Navigation({ siteNav: initialNav, siteName, darkMode, la
 
   // The active page can live in any tier (editors navigate to hidden and
   // archived pages via the Pages modal).
-  const treePages = siteNav.entries.flatMap((e) => (e.kind === "group" ? e.pages : [e]));
+  const treePages = siteNav.entries.flatMap((e) =>
+    e.kind === "group" ? e.pages : e.kind === "page" ? [e] : [],
+  );
   const activePage =
     [...treePages, ...siteNav.hidden, ...siteNav.archive].find((p) => p.isActive) ?? null;
   const headings: NavItem[] = activePage?.headings ?? [];
@@ -100,6 +103,7 @@ export default function Navigation({ siteNav: initialNav, siteName, darkMode, la
     useActiveHeadings(parentIds, childIdsByParent, grandchildIdsByChild);
 
   const handleHeadingNav = useCallback((href: string) => {
+    closeDocFile(); // a nav heading click always leaves doc mode first
     const id = href.replace("#", "");
     const el = document.getElementById(id);
     if (el) { el.scrollIntoView({ behavior: "smooth" }); setActiveSection(id); }
@@ -206,11 +210,12 @@ export default function Navigation({ siteNav: initialNav, siteName, darkMode, la
     </li>
   );
 
-  // The one collapsible-section body, shared by authored groups and the derived
-  // editor buckets so the two can never drift apart visually. Callers supply the
-  // wrapper element, because authored groups are interleaved <li>s inside the
-  // main nav list while the buckets are their own blocks below it.
-  const renderGroupBody = (key: string, label: string, pages: PageNavItem[], defaultOpen: boolean) => {
+  // The one collapsible-section body, shared by authored groups, the derived
+  // editor buckets and the derived Documents group so they can never drift
+  // apart visually. Callers supply the wrapper element, because authored groups
+  // are interleaved <li>s inside the main nav list while the buckets are their
+  // own blocks below it.
+  const renderCollapsible = (key: string, label: string, defaultOpen: boolean, body: ReactNode) => {
     const isOpen = openGroups[key] ?? defaultOpen;
     return (
       <>
@@ -223,11 +228,45 @@ export default function Navigation({ siteNav: initialNav, siteName, darkMode, la
           <span>{label}</span>
           <ChevronRight size={14} aria-hidden="true" className={cn("transition-transform", isOpen && "rotate-90")} />
         </button>
-        {isOpen && <ul className="space-y-1">{pages.map(renderPage)}</ul>}
+        {isOpen && body}
       </>
     );
   };
 
+  const renderGroupBody = (key: string, label: string, pages: PageNavItem[], defaultOpen: boolean) =>
+    renderCollapsible(key, label, defaultOpen, <ul className="space-y-1">{pages.map(renderPage)}</ul>);
+
+  // Documents are launchers, not destinations: the viewer sets the deep-link
+  // hash (the overlay atom reads it), the editor opens the atom directly —
+  // never pageSelectEvent, which would dead-end on a page that doesn't exist.
+  const renderDoc = (doc: DocNavItem) => (
+    <li key={doc.sectionId}>
+      {asButton ? (
+        <button
+          type="button"
+          onClick={() => { openDocFile(doc.sectionId); setIsOpen(false); }}
+          className="cursor-pointer w-full rounded-inner px-3 py-2 text-left text-sm font-bold text-base-contrast transition-colors hover:text-primary"
+        >
+          {doc.title}
+        </button>
+      ) : (
+        <a
+          href={`#doc=${doc.sectionId}`}
+          onClick={() => setIsOpen(false)}
+          className="block w-full rounded-inner px-3 py-2 text-left text-sm font-bold text-base-contrast transition-colors hover:text-primary"
+        >
+          {doc.title}
+        </a>
+      )}
+    </li>
+  );
+
+  const renderDocGroup = (group: DocGroupNavItem) => (
+    <li key={group.id} className="mt-2 border-t border-base-200 pt-2">
+      {renderCollapsible(group.id, group.label, true, <ul className="space-y-1">{group.docs.map(renderDoc)}</ul>)}
+    </li>
+  );
+
   const renderAuthoredGroup = (group: GroupNavItem) => (
     // No mx-4: the enclosing list is already padded, unlike the bucket blocks.
     <li key={group.id} className="mt-2 border-t border-base-200 pt-2">
@@ -288,7 +327,11 @@ export default function Navigation({ siteNav: initialNav, siteName, darkMode, la
 
         <ul className="space-y-1 px-4 py-2">
           {siteNav.entries.map((entry) =>
-            entry.kind === "group" ? renderAuthoredGroup(entry) : renderPage(entry),
+            entry.kind === "group"
+              ? renderAuthoredGroup(entry)
+              : entry.kind === "doc-group"
+                ? renderDocGroup(entry)
+                : renderPage(entry),
           )}
         </ul>
 

package/src/components/shell/EditorModal.tsx

@@ -4,6 +4,7 @@ import { RemoveIcon } from "../shared/icons";
 import { IconButton } from "../shared/IconButton";
 import { useFocusTrap } from "../../hooks/useFocusTrap";
 import { cn } from "../../lib/cn";
+import { lockBodyScroll } from "../../lib/scroll-lock";
 
 interface EditorModalProps {
   isOpen: boolean;
@@ -37,11 +38,7 @@ export function EditorModal({ isOpen, onClose, title, blocking = false, size = "
 
   useEffect(() => {
     if (!isOpen) return;
-    const original = document.body.style.overflow;
-    document.body.style.overflow = "hidden";
-    return () => {
-      document.body.style.overflow = original;
-    };
+    return lockBodyScroll();
   }, [isOpen]);
 
   if (!isOpen) return null;