@drawnagency/primitives 0.1.113 → 0.1.115

package/src/components/sections/IconList/IconListSettings.tsx

@@ -1,5 +1,5 @@
 import { useState } from "react";
-import { Check, X } from "lucide-react";
+import { Check, Hash, Shapes, X } from "lucide-react";
 import { Checkbox } from "../../shared/Checkbox";
 import { FormLabel } from "../../shared/FormLabel";
 import { IconPicker } from "../../primitives/IconPicker";
@@ -11,79 +11,117 @@ export function IconListSettings({
   showLabel: initialShowLabel,
   stackText: initialStackText,
   dodont: initialDodont,
+  marker: initialMarker,
   onChange,
 }: {
   icon: string | null;
   showLabel: boolean;
   stackText: boolean;
   dodont?: "do" | "dont";
+  marker?: "icon" | "number";
   onChange: (result: { content: Record<string, unknown>; options: Record<string, unknown> }) => void;
 }) {
   const [icon, setIcon] = useState(initialIcon);
   const [showLabel, setShowLabel] = useState(initialShowLabel);
   const [stackText, setStackText] = useState(initialStackText);
   const [dodont, setDodont] = useState<"do" | "dont" | undefined>(initialDodont);
+  // The Icon marker choice is stored as an absent key, matching every list saved
+  // before the option existed (an explicit "icon" normalises to absent on save).
+  const [marker, setMarker] = useState<"number" | undefined>(initialMarker === "number" ? "number" : undefined);
   const [pickerOpen, setPickerOpen] = useState(false);
 
   const emit = (
-    overrides: Partial<{ icon: string | null; showLabel: boolean; stackText: boolean; dodont: "do" | "dont" | undefined }>,
-  ) => onChange({ content: {}, options: { icon, showLabel, stackText, dodont, ...overrides } });
+    overrides: Partial<{
+      icon: string | null;
+      showLabel: boolean;
+      stackText: boolean;
+      dodont: "do" | "dont" | undefined;
+      marker: "number" | undefined;
+    }>,
+  ) => onChange({ content: {}, options: { icon, showLabel, stackText, dodont, marker, ...overrides } });
 
   const iconEntry = icon ? getIcon(icon) : null;
   const dodontActive = dodont === "do" || dodont === "dont";
+  const numbered = marker === "number" && !dodontActive;
+  const iconDisabled = dodontActive || numbered;
 
-  const tile = (value: "do" | "dont" | undefined, label: string, aria: string, glyph: React.ReactNode, tint: string) => (
+  // Numbering is for standard icon lists only, so turning on Do/Don't drops it.
+  const pickDodont = (value: "do" | "dont" | undefined) => {
+    setDodont(value);
+    if (value) {
+      setMarker(undefined);
+      emit({ dodont: value, marker: undefined });
+    } else {
+      emit({ dodont: value });
+    }
+  };
+
+  const tile = (pressed: boolean, onPick: () => void, label: string, aria: string, glyph: React.ReactNode, tint: string) => (
     <button
       type="button"
       aria-label={aria}
-      aria-pressed={dodont === value}
+      aria-pressed={pressed}
       className={cn(
         "cursor-pointer flex flex-col items-center gap-1 rounded border py-2 transition-colors",
         tint,
-        dodont === value ? "border-primary bg-base-accent" : "border-base-200",
+        pressed ? "border-primary bg-base-accent" : "border-base-200",
       )}
-      onClick={() => { setDodont(value); emit({ dodont: value }); }}
+      onClick={onPick}
     >
       {glyph}
       <span className="text-xs font-medium">{label}</span>
     </button>
   );
+  const dodontTile = (value: "do" | "dont" | undefined, label: string, aria: string, glyph: React.ReactNode, tint: string) =>
+    tile(dodont === value, () => pickDodont(value), label, aria, glyph, tint);
+  const markerTile = (value: "number" | undefined, label: string, aria: string, glyph: React.ReactNode) =>
+    tile(marker === value, () => { setMarker(value); emit({ marker: value }); }, label, aria, glyph, "text-base-contrast-light");
 
   return (
     <div className="space-y-4">
       <div>
         <FormLabel>Do / Don't list</FormLabel>
         <div className="grid grid-cols-3 gap-2">
-          {tile(
+          {dodontTile(
             undefined,
             "None",
             "No do/don't",
             <span className="flex h-5 w-5 items-center justify-center rounded-sm border border-dashed border-base-contrast-light/40" />,
             "text-base-contrast-light",
           )}
-          {tile("do", "Do", "Do list", <Check size={20} />, "text-green-600")}
-          {tile("dont", "Don't", "Don't list", <X size={20} />, "text-red-600")}
+          {dodontTile("do", "Do", "Do list", <Check size={20} />, "text-success")}
+          {dodontTile("dont", "Don't", "Don't list", <X size={20} />, "text-danger")}
         </div>
       </div>
 
+      {!dodontActive && (
+        <div>
+          <FormLabel>Marker</FormLabel>
+          <div className="grid grid-cols-2 gap-2">
+            {markerTile(undefined, "Icon", "Icon markers", <Shapes size={20} />)}
+            {markerTile("number", "Number", "Number markers", <Hash size={20} />)}
+          </div>
+        </div>
+      )}
+
       <div className="relative">
         <FormLabel htmlFor="icon-picker-btn">Default Icon</FormLabel>
         <div className="flex items-center gap-2">
           <button
             id="icon-picker-btn"
-            disabled={dodontActive}
+            disabled={iconDisabled}
             className={cn(
               "flex items-center gap-2 rounded border border-base-200 px-3 py-1.5 text-sm text-base-contrast-light",
-              dodontActive
+              iconDisabled
                 ? "cursor-not-allowed opacity-50"
                 : "cursor-pointer hover:border-primary hover:text-primary",
             )}
-            onClick={() => { if (!dodontActive) setPickerOpen((prev) => !prev); }}
+            onClick={() => { if (!iconDisabled) setPickerOpen((prev) => !prev); }}
           >
             {iconEntry && <iconEntry.icon size={16} />}
             <span>{iconEntry?.label ?? "None"}</span>
           </button>
-          {icon && !dodontActive && (
+          {icon && !iconDisabled && (
             <button
               className="cursor-pointer text-xs text-base-contrast-light hover:text-base-contrast"
               onClick={() => { setIcon(null); emit({ icon: null }); }}
@@ -92,12 +130,12 @@ export function IconListSettings({
             </button>
           )}
         </div>
-        {dodontActive && (
+        {iconDisabled && (
           <p className="mt-1 text-xs text-base-contrast-light/70">
-            Whole-list Do/Don't overrides the default icon.
+            {numbered ? "Numbered lists don't show icons." : "Whole-list Do/Don't overrides the default icon."}
           </p>
         )}
-        {pickerOpen && !dodontActive && (
+        {pickerOpen && !iconDisabled && (
           <div className="absolute top-full left-0 z-50 mt-1">
             <IconPicker
               selected={icon}

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

@@ -40,6 +40,12 @@ const schema = z.object({
         .enum(["do", "dont"])
         .describe("Whole-list do/don't mode: render every item with a green check (do) or red x (don't).")
         .optional(),
+      marker: z
+        .enum(["icon", "number"])
+        .describe(
+          "What marks each item: \"icon\" (default when absent) or \"number\" — bold numerals 1, 2, 3… in place of icons, ignoring item and default icons. Standard lists only: ignored when options.dodont is set.",
+        )
+        .optional(),
     })
     .optional(),
 });
@@ -72,7 +78,7 @@ export default defineSection({
   icon: <List size={18} />,
   schema,
   authoringNote:
-    "A list of labeled items, optionally with per-item icons and do/don't markers. Use for feature lists, guidelines, or do/don't guidance.",
+    "A list of labeled items, optionally with per-item icons and do/don't markers, or numbered instead (options.marker: \"number\"). Use for feature lists, guidelines, steps, or do/don't guidance.",
   component: ({ content, options, onChange }) => (
     <IconList
       items={content.content.items}
@@ -80,11 +86,12 @@ export default defineSection({
       showLabel={options?.showLabel as boolean}
       stackText={options?.stackText as boolean}
       dodont={options?.dodont as "do" | "dont" | undefined}
-      // IconList rebuilds its options from the four props above, which inside a
+      marker={options?.marker as "icon" | "number" | undefined}
+      // IconList rebuilds its options from the five props above, which inside a
       // container are childDefaults merged with the child's own options — writing
       // that back would materialise the container's defaults onto the child (it
       // then stops following later default changes) and drop any option key
-      // outside those four. Only items change here, so keep the stored options.
+      // outside those five. Only items change here, so keep the stored options.
       onChange={
         onChange ? (c) => onChange({ ...(c as typeof content), options: content.options }) : undefined
       }

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

@@ -1,5 +1,5 @@
 import { Heading1 } from "lucide-react";
-import { defineHeadingSection } from "../../primitives/defineHeadingSection";
+import { defineHeadingSection } from "../../primitives/define-heading-section";
 
 export default defineHeadingSection({
   type: "link_heading",

package/src/components/sections/Media/MediaBlock.tsx

@@ -1,4 +1,4 @@
-import type { SingleMediaReference } from "../../../schemas/shared";
+import type { ImageBackground, SingleMediaReference } from "../../../schemas/shared";
 import type { LinkValue } from "../../../schemas/link";
 import { cn } from "../../../lib/cn";
 import { ResolvedMedia } from "../../primitives/ResolvedMedia";
@@ -6,10 +6,17 @@ import { ImageDropZone } from "../../primitives/ImageDropZone";
 import { EditablePlainText } from "../../primitives/EditablePlainText";
 import { useMediaLibrary } from "../../shell/MediaLibraryContext";
 import { rebindImageRef } from "../../../media/resolve";
+import { imageBackdrop } from "../../../lib/image-background";
 
 export interface MediaBlockProps {
   refValue: SingleMediaReference;
-  options: { square?: boolean; showCaption?: boolean; border?: boolean; objectFit?: "cover" | "contain" };
+  options: {
+    square?: boolean;
+    showCaption?: boolean;
+    border?: boolean;
+    objectFit?: "cover" | "contain";
+    background?: ImageBackground;
+  };
   /** Per-item link (viewer: already resolved to kind:"external" upstream). */
   link?: LinkValue;
   isEditMode: boolean;
@@ -22,6 +29,9 @@ export function MediaBlock({ refValue, options, link, isEditMode, onRefChange }:
   const fit = refValue.objectFit ?? options.objectFit;
   const fitClass = fit === "cover" ? "object-cover" : "object-contain";
   const showBorder = refValue.border ?? options.border;
+  // Image-only: a backdrop behind a video would just frame its letterboxing.
+  // Per placement by design (#60): not inheritable, and no per-ref override.
+  const backdrop = refValue.type === "video" ? undefined : imageBackdrop(options.background);
   const captionStr = refValue.caption
     ? Array.isArray(refValue.caption) ? refValue.caption.join("\n") : refValue.caption
     : "";
@@ -49,6 +59,7 @@ export function MediaBlock({ refValue, options, link, isEditMode, onRefChange }:
       className="h-full w-full"
       imgClassName={fitClass}
       invertFrom={refValue.invertFrom}
+      backdrop={backdrop}
     />
   );
 

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

@@ -1,9 +1,9 @@
 import { defineSection } from "../../../lib/registry";
 import { z } from "zod";
 import { Image as ImageIcon } from "lucide-react";
-import { SingleMediaReferenceSchema } from "../../../schemas/shared";
+import { SingleMediaReferenceSchema, ImageBackgroundSchema } from "../../../schemas/shared";
 import { LinkValueSchema, DEFAULT_LINK } from "../../../schemas/link";
-import { MediaBlock } from "./MediaBlock";
+import { MediaBlock, type MediaBlockProps } from "./MediaBlock";
 
 const schema = z.object({
   type: z.literal("media"),
@@ -24,6 +24,9 @@ const schema = z.object({
         .enum(["cover", "contain"])
         .describe("How the image fills its box: 'contain' (fit whole image) or 'cover' (fill and crop).")
         .optional(),
+      background: ImageBackgroundSchema.describe(
+        "Optional backdrop filling the image box, for images that need contrast (e.g. a white transparent logo). 'theme' picks the site's light or dark surface separately for light and dark mode; 'custom' uses one hex for both. Images only — ignored for video. Omit for none.",
+      ).optional(),
     })
     .default({}),
 });
@@ -38,7 +41,7 @@ export default defineSection({
   component: ({ content, options, onChange }) => (
     <MediaBlock
       refValue={content.content.ref}
-      options={(options ?? {}) as { square?: boolean; showCaption?: boolean; border?: boolean; objectFit?: "cover" | "contain" }}
+      options={(options ?? {}) as MediaBlockProps["options"]}
       link={content.content.link}
       isEditMode={!!onChange}
       onRefChange={
@@ -69,11 +72,16 @@ export default defineSection({
         { label: "Cover", value: "cover" },
       ],
     },
+    background: {
+      type: "image-background",
+      label: "Image background",
+      hidden: (values) => (values.ref as { type?: string } | undefined)?.type === "video",
+    },
     link: { type: "link", label: "Link", default: DEFAULT_LINK, target: "content" },
   },
   inheritableSettings: ["square", "showCaption", "border", "objectFit"],
   settingsTabs: [
-    { label: "Display", fields: ["square", "showCaption", "border", "objectFit"] },
+    { label: "Display", fields: ["square", "showCaption", "border", "objectFit", "background"] },
     { label: "Link", fields: ["link"] },
   ],
 });

package/src/components/sections/Reference/ReferenceList.tsx

@@ -0,0 +1,214 @@
+import { useContext, useMemo } from "react";
+import { ArrowUpRight } from "lucide-react";
+import { cn } from "../../../lib/cn";
+import { getSection } from "../../../lib/registry";
+import { audiencePasses, pageDisplayTitle } from "../../../lib/pages";
+import {
+  referenceItems, type ReferenceContent, type ReferenceExclusion, type ReferenceItem,
+} from "../../../lib/references";
+import { ReferenceSourcesContext, type ReferenceSources } from "../../shared/ReferenceSourcesContext";
+import { SummaryAnchorsContext } from "../../shared/SummaryAnchorsContext";
+import { useOptionalEditorContext } from "../../shell/EditorContext";
+import { Button } from "../../shared/Button";
+
+type ViewBranch = "saved" | "live";
+
+/** Everything the canvas does with an item the published site drops, by why
+ *  it drops it. `renders`: whether there is a copy to draw at all (a dangling
+ *  pick has no source; a nested Reference is never expanded). `inPreview`:
+ *  whether the preview still shows it, mirroring how it treats native sections. */
+const EXCLUSIONS: Record<ReferenceExclusion, {
+  reason: (item: ReferenceItem) => string;
+  renders: boolean;
+  inPreview: (item: ReferenceItem, viewBranch: ViewBranch) => boolean;
+}> = {
+  missing: {
+    reason: (i) => `Not found — deleted, unreadable, or not a top-level section (${i.sectionId})`,
+    renders: false,
+    inPreview: () => false,
+  },
+  reference: { reason: () => "Another Reference — never shown", renders: false, inPreview: () => false },
+  "archived-page": { reason: () => "On an archived page", renders: true, inPreview: () => false },
+  "not-live": {
+    reason: (i) => (i.source?.meta.status === "archived" ? "Archived section" : "Draft — publish it to show it here"),
+    renders: true,
+    // The Unpublished preview dims drafts and hides archived sections.
+    inPreview: (i, viewBranch) => viewBranch === "saved" && i.source?.meta.status === "draft",
+  },
+};
+
+const shownInPreview = (item: ReferenceItem, viewBranch: ViewBranch) =>
+  item.excluded === null || EXCLUSIONS[item.excluded].inPreview(item, viewBranch);
+
+/**
+ * Whether a Reference draws anything in preview. The viewer renders no wrapper
+ * for an empty Reference, so EditorContent skips its wrapper in preview too.
+ * Audience-independent: an audience preview dims copies, it never removes them.
+ */
+export function referenceShowsInPreview(
+  sources: ReferenceSources, referenceId: string, content: ReferenceContent, viewBranch: ViewBranch,
+): boolean {
+  return referenceItems({ referenceId, content, index: sources.index, allSections: sources.sections, audiences: [] })
+    .some((item) => shownInPreview(item, viewBranch));
+}
+
+const NO_SUMMARY_ANCHORS = {};
+
+/**
+ * A Reference on the editor canvas, laid out exactly as the viewer lays out
+ * the sections it expands to — copy after copy, each 2.25rem below the last
+ * (a `.section-wrapper`'s top padding; the Reference's own wrapper supplies the
+ * first copy's) — so toggling between editing and preview never moves
+ * anything. Everything editor-only (where a copy comes from, why the site
+ * drops it, which of the page's audiences can't see it, Edit source) is an
+ * overlay that takes no space.
+ *
+ * Which copies show follows how the canvas treats native sections: edit mode
+ * lists every item, greyed with the reason when the published site drops it
+ * (a dangling pick or a nested Reference as an empty greyed row);
+ * the Unpublished preview hides archived ones and dims drafts; the Published
+ * preview shows exactly what the viewer resolves (EditorShell hands it the
+ * `main` branch's content then). An audience preview dims what that audience
+ * can't see. The audience warnings are relative to who can see this Reference
+ * — the page's audiences narrowed by the Reference's own access; when that
+ * leaves no one, the whole Reference says so.
+ */
+export function ReferenceList({ referenceId, content, isEditMode }: {
+  referenceId: string;
+  content: ReferenceContent;
+  isEditMode: boolean;
+}) {
+  const sources = useContext(ReferenceSourcesContext);
+  const editor = useOptionalEditorContext();
+  const viewBranch = editor?.viewBranch ?? "saved";
+  const previewAudience = editor?.previewAudience ?? null;
+
+  const model = useMemo(() => {
+    if (!sources) return null;
+    const { index, sections, audiences } = sources;
+    const page = index.pages.find((p) => p.order.includes(referenceId));
+    const access = index.sections[referenceId]?.access ?? [];
+    const viewers = audiences.filter((a) => audiencePasses(page?.access ?? [], a.name) && audiencePasses(access, a.name));
+    const items = referenceItems({
+      referenceId, content, index, allSections: sections, audiences: viewers.map((a) => a.name),
+    });
+    return {
+      items,
+      // Copies carry the page-wide anchors the editor nav links to, so no
+      // heading here duplicates its source's DOM id or another Reference's.
+      copyById: sources.copies[referenceId] ?? {},
+      displayName: new Map(viewers.map((a) => [a.name, a.displayName])),
+      viewerCount: viewers.length,
+      // The site has audiences, yet none passes both the page's access and the
+      // Reference's own: no one can ever see a copy here. (Empty access is
+      // "everyone", so an unrestricted page or Reference never lands here.)
+      noViewers: audiences.length > 0 && viewers.length === 0,
+      // Absent `tags` is "not loaded": tagged sections can't be listed yet.
+      tagsUnloaded: index.tags === undefined && content.tagIds.length > 0,
+    };
+  }, [sources, referenceId, content]);
+
+  if (!sources || !model) {
+    return isEditMode ? <Placeholder>Reference: shown as live copies on the published site.</Placeholder> : null;
+  }
+
+  // Edit mode lists every item, greyed with its reason when the site drops it;
+  // preview shows what the canvas shows for native sections.
+  const shown = isEditMode ? model.items : model.items.filter((item) => shownInPreview(item, viewBranch));
+
+  const notes = [
+    model.tagsUnloaded && "Tags haven't loaded, so tagged sections aren't listed yet.",
+    model.noViewers && "No audience can see this Reference on this page",
+  ].filter((n): n is string => !!n);
+
+  if (shown.length === 0) {
+    // EditorContent skips an empty Reference's wrapper in preview
+    // (referenceShowsInPreview); this covers rendering without it.
+    if (!isEditMode) return null;
+    if (notes.length === 0) return <Placeholder>Reference: no tags or sections chosen yet.</Placeholder>;
+    return <Placeholder>{["Reference: nothing to show.", ...notes].join(" ")}</Placeholder>;
+  }
+
+  return (
+    // The page's summary anchors are keyed by section id, so a copy of a
+    // summary also on this page would take its native anchor; emptying the
+    // context leaves every copy on the anchor stamped for it.
+    <SummaryAnchorsContext.Provider value={NO_SUMMARY_ANCHORS}>
+      {shown.map((item, n) => {
+        const { source } = item;
+        const exclusion = item.excluded ? EXCLUSIONS[item.excluded] : null;
+        const drawn = source && (!exclusion || exclusion.renders) ? source : null;
+        const definition = source ? getSection(source.section.type) : undefined;
+        const copy = drawn ? model.copyById[item.sectionId] ?? drawn.section : null;
+        const Component = definition?.component;
+        const reason = exclusion?.reason(item) ?? null;
+        const hiddenForAll = model.noViewers || (model.viewerCount > 0 && item.hiddenFrom.length === model.viewerCount);
+        const previewHidden = previewAudience !== null && !!source &&
+          (!audiencePasses(item.page?.access ?? [], previewAudience) || !audiencePasses(source.meta.access, previewAudience));
+        const typeLabel = definition?.label ?? source?.section.type ?? "Section";
+        const label = (source && definition?.getLabel?.(source.section)) || typeLabel;
+
+        return (
+          <div key={item.sectionId} className={cn(n > 0 && "pt-9")}>
+            <div
+              data-reference-item={item.sectionId}
+              className={cn(
+                // `group` mirrors the viewer's per-section wrapper for the copy's
+                // own hover styles; `group/copy` scopes Edit source to this copy,
+                // since the Reference's wrapper is a `group` too.
+                "group group/copy relative",
+                isEditMode && "rounded-outer hover:outline hover:outline-1 hover:outline-dashed hover:outline-primary/40",
+                previewHidden ? "opacity-15 transition-opacity duration-200 hover:opacity-100"
+                  : (isEditMode ? reason || hiddenForAll : item.excluded) && "opacity-50",
+              )}
+            >
+              {/* inert while editing: a copy is read-only — edits happen on its source. */}
+              <div inert={isEditMode}>
+                {!copy && <div className="min-h-20 rounded-md border-2 border-dashed" />}
+                {copy && Component && (
+                  <Component
+                    content={copy}
+                    options={"options" in copy ? (copy.options as Record<string, unknown>) : undefined}
+                    isEditMode={false}
+                  />
+                )}
+              </div>
+              {isEditMode && (
+                <div className="absolute right-2 top-2 z-20 flex max-w-[calc(100%-1rem)] flex-wrap items-center justify-end gap-1">
+                  {n === 0 && notes.map((note) => <Badge key={note}>{note}</Badge>)}
+                  {reason && <Badge>{reason}</Badge>}
+                  {!reason && hiddenForAll && !model.noViewers && <Badge>Hidden for all of this page's audiences</Badge>}
+                  {!reason && !hiddenForAll && item.hiddenFrom.length > 0 && (
+                    <Badge>{`Hidden from ${item.hiddenFrom.map((a) => model.displayName.get(a) ?? a).join(", ")}`}</Badge>
+                  )}
+                  {source && <span className="flex items-center gap-2 rounded-full border border-base-200 bg-base px-2 py-0.5 text-xs opacity-0 shadow-sm transition-opacity focus-within:opacity-100 group-hover/copy:opacity-100">
+                    <span className="max-w-56 truncate text-base-contrast-light">
+                      {item.page ? `${pageDisplayTitle(item.page.title)} · ` : ""}{label}
+                    </span>
+                    <Button variant="ghost" className="inline-flex items-center gap-0.5" onClick={() => sources.jumpToSection(item.sectionId)}>
+                      Edit source <ArrowUpRight size={12} aria-hidden="true" />
+                    </Button>
+                  </span>}
+                </div>
+              )}
+            </div>
+          </div>
+        );
+      })}
+    </SummaryAnchorsContext.Provider>
+  );
+}
+
+function Badge({ children }: { children: string }) {
+  return (
+    <span className="rounded-full border border-warning bg-warning-bg px-2 py-0.5 text-xs text-warning shadow-sm">{children}</span>
+  );
+}
+
+function Placeholder({ children }: { children: string }) {
+  return (
+    <div className="flex min-h-20 items-center justify-center rounded-md border-2 border-dashed px-4 text-center text-xs text-base-contrast-light/50">
+      {children}
+    </div>
+  );
+}

package/src/components/sections/Reference/ReferenceSettings.tsx

@@ -0,0 +1,159 @@
+import { useContext, useState } from "react";
+import { cn } from "../../../lib/cn";
+import { getSection } from "../../../lib/registry";
+import { pageDisplayTitle } from "../../../lib/pages";
+import { pagesInNavOrder } from "../../../lib/nav-tree";
+import { siteTags, tagDisplayLabel } from "../../../lib/tags";
+import { pluralize } from "../../../lib/text";
+import { toThumbViews, type ThumbView } from "../../../lib/thumb-views";
+import { REFERENCE_TYPE } from "../../../lib/reference-type";
+import type { ReferenceContent } from "../../../lib/references";
+import { ReferenceSourcesContext } from "../../shared/ReferenceSourcesContext";
+import { SectionSummaryRow } from "../../shared/SectionSummaryRow";
+import { Checkbox, CheckboxBox } from "../../shared/Checkbox";
+import { Tabs } from "../../shared/Tabs";
+
+const panel = "flex min-h-0 flex-1 flex-col gap-4 overflow-y-auto px-px";
+
+/**
+ * Tags and Sections, combined as a union. Ids the registry or index no longer
+ * knows are listed too, so an editor can see them and clear them — the viewer
+ * drops them silently.
+ */
+export function ReferenceSettings({
+  tagIds = [],
+  sectionIds = [],
+  onChange,
+}: Partial<ReferenceContent> & { onChange: (result: { content: ReferenceContent }) => void }) {
+  const sources = useContext(ReferenceSourcesContext);
+  const [v, setV] = useState<ReferenceContent>({ tagIds, sectionIds });
+
+  const update = (next: ReferenceContent) => {
+    setV(next);
+    onChange({ content: next });
+  };
+  const toggle = (list: string[], id: string, on: boolean) => (on ? [...list, id] : list.filter((x) => x !== id));
+
+  if (!sources) return null;
+  const { index, sections, mediaManifest } = sources;
+
+  // Absent `tags` is "not loaded", not "none": every stored tag would read as
+  // deleted, and clearing one would drop a real tag. Hold the tab read-only.
+  const tagsLoaded = index.tags !== undefined;
+  const tags = siteTags(index);
+  const deletedTagIds = tagsLoaded ? v.tagIds.filter((id) => !tags.some((t) => t.id === id)) : [];
+
+  const byId = new Map(sections.map((s) => [s.section.id, s]));
+  const pageGroups = pagesInNavOrder(index)
+    .map((page) => ({
+      page,
+      rows: page.order.flatMap((id) => {
+        const s = byId.get(id);
+        // References can't be picked; one already picked (by an agent) is
+        // listed so it can be cleared.
+        return s && (s.section.type !== REFERENCE_TYPE || v.sectionIds.includes(id)) ? [s] : [];
+      }),
+    }))
+    .filter((g) => g.rows.length > 0);
+  const onAPage = new Set(pageGroups.flatMap((g) => g.rows.map((s) => s.section.id)));
+  const deletedSectionIds = v.sectionIds.filter((id) => !onAPage.has(id));
+
+  const tagsTab = (
+    <div className={panel}>
+      {!tagsLoaded && (
+        <p className="text-sm text-base-contrast-light">Tags haven't loaded, so they can't be changed right now.</p>
+      )}
+      {tagsLoaded && tags.length === 0 && deletedTagIds.length === 0 && (
+        <p className="text-sm text-base-contrast-light">
+          No tags yet. Add them from a section's Tags pill or under Site settings → Tags.
+        </p>
+      )}
+      {tags.map((t) => (
+        <Checkbox
+          key={t.id}
+          label={tagDisplayLabel(t.label)}
+          description={pluralize(t.sectionIds.length, "section")}
+          checked={v.tagIds.includes(t.id)}
+          onChange={(on) => update({ ...v, tagIds: toggle(v.tagIds, t.id, on) })}
+        />
+      ))}
+      {deletedTagIds.map((id) => (
+        <Checkbox
+          key={id}
+          label="Deleted tag"
+          description="Shows nothing. Untick to remove it."
+          checked
+          onChange={() => update({ ...v, tagIds: toggle(v.tagIds, id, false) })}
+        />
+      ))}
+    </div>
+  );
+
+  const sectionRow = (id: string, label: string, typeLabel: string, thumbs: ThumbView[], status?: string) => {
+    const checked = v.sectionIds.includes(id);
+    return (
+      <button
+        key={id}
+        type="button"
+        role="checkbox"
+        aria-checked={checked}
+        aria-label={`${typeLabel}: ${label}`}
+        onClick={() => update({ ...v, sectionIds: toggle(v.sectionIds, id, !checked) })}
+        className="flex w-full cursor-pointer text-left"
+      >
+        <SectionSummaryRow
+          label={label}
+          typeLabel={typeLabel}
+          thumbnails={thumbs}
+          className={cn(checked && "border-primary")}
+          trailing={
+            <>
+              {status && status !== "live" && <span className="text-xs capitalize text-base-contrast-light">{status}</span>}
+              <CheckboxBox checked={checked} />
+            </>
+          }
+        />
+      </button>
+    );
+  };
+
+  const sectionsTab = (
+    <div className={panel}>
+      {pageGroups.map(({ page, rows }) => (
+        <section key={page.id} className="flex flex-col gap-2">
+          <h3 className="text-xs font-medium uppercase tracking-wide text-base-contrast-light">
+            {pageDisplayTitle(page.title)}
+            {page.status === "archived" && " (archived)"}
+          </h3>
+          {rows.map((s) => {
+            const def = getSection(s.section.type);
+            const typeLabel = def?.label ?? s.section.type;
+            return sectionRow(
+              s.section.id,
+              def?.getLabel?.(s.section) ?? typeLabel,
+              typeLabel,
+              toThumbViews(def?.getThumbnails?.(s.section) ?? [], mediaManifest),
+              s.meta.status,
+            );
+          })}
+        </section>
+      ))}
+      {deletedSectionIds.length > 0 && (
+        <section className="flex flex-col gap-2">
+          <h3 className="text-xs font-medium uppercase tracking-wide text-base-contrast-light">Not found</h3>
+          {deletedSectionIds.map((id) => sectionRow(id, "Section not found", "Deleted or can't be read", []))}
+        </section>
+      )}
+    </div>
+  );
+
+  return (
+    <Tabs
+      fullBleedTabBar
+      tabs={[
+        { id: "tags", label: `Tags${v.tagIds.length ? ` (${v.tagIds.length})` : ""}`, content: tagsTab },
+        { id: "sections", label: `Sections${v.sectionIds.length ? ` (${v.sectionIds.length})` : ""}`, content: sectionsTab },
+      ]}
+    />
+  );
+}