@drawnagency/primitives 0.1.99 → 0.1.101

package/src/components/primitives/DocumentDropZone.tsx

@@ -0,0 +1,79 @@
+import { useState, type DragEvent } from "react";
+import { FileUp } from "lucide-react";
+import { cn } from "../../lib/cn";
+import { DOCUMENT_MIME_TO_EXT } from "../../schemas/documents";
+import { useMediaLibrary } from "../shell/MediaLibraryContext";
+
+interface DocumentDropZoneProps {
+  /** Fired with the staged/committed document id once the upload resolves. */
+  onDocumentSelected: (documentId: string) => void;
+  className?: string;
+}
+
+const isDocumentFile = (file: File) => file.type in DOCUMENT_MIME_TO_EXT;
+
+/**
+ * The empty state of a `document` section in edit mode: drop a PDF/HTML file to
+ * upload it, or click to pick one from the library. Editor-only — the viewer
+ * never renders an unconfigured document section at all.
+ *
+ * Deliberately thin on validation: every rejection (wrong type, too large, no
+ * documents store) belongs to `uploadDocument`, which already routes typed copy
+ * through the pipeline's `onUploadError` → `UploadRejectionAlert` channel. The
+ * one judgement made here is WHICH file of a multi-file drop to hand over.
+ */
+export function DocumentDropZone({ onDocumentSelected, className }: DocumentDropZoneProps) {
+  const mediaLibrary = useMediaLibrary();
+  const [dragging, setDragging] = useState(false);
+
+  // Only react to drags carrying files, so the editor's block reorder (which
+  // carries no `Files`) passes straight through. Mirrors ImageDropZone.
+  const hasFiles = (e: DragEvent) => e.dataTransfer.types.includes("Files");
+
+  const handleDragOver = (e: DragEvent) => {
+    if (!hasFiles(e)) return;
+    e.preventDefault();
+    e.dataTransfer.dropEffect = "copy";
+    setDragging(true);
+  };
+
+  const handleDragLeave = (e: DragEvent) => {
+    if (!hasFiles(e)) return;
+    const related = e.relatedTarget as Node | null;
+    if (related && e.currentTarget.contains(related)) return;
+    setDragging(false);
+  };
+
+  const handleDrop = (e: DragEvent) => {
+    if (!hasFiles(e)) return;
+    e.preventDefault();
+    e.stopPropagation();
+    setDragging(false);
+    const files = Array.from(e.dataTransfer.files);
+    if (files.length === 0) return;
+    // First document-typed file wins. With none, the first file still goes to
+    // the pipeline so its rejection names the real constraint ("only PDF and
+    // HTML documents can be uploaded") instead of a hand-rolled message here.
+    void mediaLibrary?.uploadDocument?.(files.find(isDocumentFile) ?? files[0], onDocumentSelected);
+  };
+
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        mediaLibrary?.openSelectModal(onDocumentSelected, { kinds: ["document"] })
+      }
+      onDragOver={handleDragOver}
+      onDragLeave={handleDragLeave}
+      onDrop={handleDrop}
+      className={cn(
+        "flex w-full cursor-pointer items-center justify-center gap-2 rounded-outer border-2 border-dashed border-base-200 bg-base px-4 py-6 text-sm text-base-contrast-light transition-colors hover:border-base-300 hover:bg-base-accent hover:text-base-contrast",
+        dragging && "border-primary bg-primary/5 text-base-contrast",
+        className,
+      )}
+    >
+      <FileUp size={18} aria-hidden="true" className="shrink-0" />
+      <span>Drop a PDF or HTML file, or choose from the library</span>
+    </button>
+  );
+}

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

@@ -0,0 +1,194 @@
+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 { DocumentDropZone } from "../../primitives/DocumentDropZone";
+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,
+  documentId = "",
+  isEditMode,
+  onDocumentSelected,
+}: {
+  sectionId: string;
+  title: string;
+  /** Raw `content.doc.documentId`. Empty means UNCONFIGURED, which is a
+   *  different state from an id that no longer resolves (see below). */
+  documentId?: string;
+  isEditMode: boolean;
+  /** Present only when the section is editable — wires a picked/uploaded id
+   *  back into content. Absent for viewers and for a locked/read-only render. */
+  onDocumentSelected?: (documentId: string) => void;
+}) {
+  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;
+
+  // An empty id is an unconfigured section: give editors somewhere to drop a
+  // file instead of a dead, permanently-disabled row. A NON-empty id that does
+  // not resolve is a different problem — it keeps the "File missing" row so the
+  // broken reference stays visible rather than looking like a fresh section.
+  if (isEditMode && !documentId && onDocumentSelected) {
+    return <DocumentDropZone onDocumentSelected={onDocumentSelected} />;
+  }
+
+  // `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, onChange }) => (
+    <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}
+      documentId={content.content.doc?.documentId ?? ""}
+      isEditMode={isEditMode}
+      // Writes `doc` only: `title` stays the editor's (deriveSiteDocuments
+      // applies the filename-stem fallback for display) and showInDocumentsNav
+      // is untouched. Spreading `content` preserves the id and layout envelope,
+      // which the container path (Container.tsx updateChild) also re-attaches.
+      onDocumentSelected={
+        onChange
+          ? (documentId) =>
+              onChange({
+                ...content,
+                content: { ...content.content, doc: { ...content.content.doc, documentId } },
+              })
+          : undefined
+      }
+    />
+  ),
+  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;