@drawnagency/primitives 0.1.113 → 0.1.114

package/src/lib/brand-swatches.ts

@@ -0,0 +1,32 @@
+import type { Section } from "../schemas/sections";
+import type { ColorItem } from "../components/sections/Colors/schema";
+
+export interface BrandSwatch {
+  hex: string;
+  name: string | undefined;
+}
+
+type Block = { type?: unknown; content?: unknown };
+
+/**
+ * Every hex value from every Colors section, walking container children, in
+ * page order and deduped case-insensitively. Swatches are offered as plain hex
+ * values: color items carry no stable id, so a picked swatch is copied, not linked.
+ */
+export function collectBrandSwatches(sections: Section[]): BrandSwatch[] {
+  const seen = new Map<string, BrandSwatch>();
+  const visit = (block: Block) => {
+    const content = (block.content ?? {}) as { colors?: unknown; children?: unknown };
+    if (block.type === "colors" && Array.isArray(content.colors)) {
+      for (const item of content.colors as ColorItem[]) {
+        for (const space of item.spaces) {
+          const hex = space.hex?.toLowerCase();
+          if (hex && !seen.has(hex)) seen.set(hex, { hex, name: item.name });
+        }
+      }
+    }
+    if (Array.isArray(content.children)) (content.children as Block[]).forEach(visit);
+  };
+  sections.forEach(visit);
+  return [...seen.values()];
+}

package/src/lib/container-ops.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from "react";
 import type { Section } from "../schemas/sections";
 import { getAllSections } from "./registry";
 import { sortInsertMenuOptions } from "./insert-menu";
+import { REFERENCE_TYPE } from "./reference-type";
 
 interface ContainerContent {
   columns: number;
@@ -37,13 +38,14 @@ export function reorderChild(container: Section, from: number, to: number): Sect
 
 /**
  * Block types insertable as a container CHILD — excludes `container` itself
- * (v1 enforces one level of container nesting). Shared so the depth guard has a
- * single, testable source of truth (the container toolbar's "+" picker uses it).
+ * (v1 enforces one level of container nesting) and `reference`, which only
+ * expands at the top level of a page. Shared so the depth guard has a single,
+ * testable source of truth (the container toolbar's "+" picker uses it).
  */
 export function childInsertableTypes(): { type: string; label: string; icon: ReactNode }[] {
   return sortInsertMenuOptions(
     getAllSections()
-      .filter((d) => d.type !== "container" && d.type !== "spacer")
+      .filter((d) => d.type !== "container" && d.type !== "spacer" && d.type !== REFERENCE_TYPE)
       .map((d) => ({ type: d.type, label: d.label, icon: d.icon })),
   );
 }

package/src/lib/dexie.ts

@@ -1,7 +1,13 @@
+// The editor's offline draft store (IndexedDB via Dexie): unsaved section
+// edits, the working index/nav, site config, pending media, and a sha-keyed
+// cache of the last loaded content. Nothing here is authoritative — GitHub is.
+// Schema versions only ever append; an EMPTY `version(N)` bump is intentional
+// (see the per-version notes in the constructor), never a leftover to remove.
 import Dexie from "dexie";
 import type { SectionContent } from "../schemas/sections";
 import type { SiteIndex, SectionMeta, SiteConfig, Page } from "../schemas/site-config";
 import type { NavEntry } from "../schemas/nav";
+import type { TagEntry } from "../schemas/tags";
 import type { LoadedSection } from "./loader";
 import type { MediaManifest, MediaItem } from "../media/types";
 import type { DocumentManifest, DocumentManifestEntry } from "../schemas/documents";
@@ -19,6 +25,9 @@ interface SiteIndexRow {
   sections: Record<string, SectionMeta>;
   /** Optional: rows written before page groups shipped have no nav. */
   nav?: NavEntry[];
+  /** Optional: rows written before section tags shipped have none. Restored
+   *  as absent (not []), which writers read as "leave tags.json alone". */
+  tags?: TagEntry[];
   deletedSections: string[];
   updatedAt: string;
 }
@@ -311,7 +320,10 @@ export async function restoreLocalChanges(): Promise<{
     const siteId = metaRow?.siteId || getDb().siteId;
     return {
       sections,
-      siteIndex: { siteId, pages: indexRow.pages, sections: indexRow.sections, nav: indexRow.nav },
+      siteIndex: {
+        siteId, pages: indexRow.pages, sections: indexRow.sections, nav: indexRow.nav,
+        ...(indexRow.tags !== undefined ? { tags: indexRow.tags } : {}),
+      },
       siteConfig: configRow?.config,
       deletedSections: indexRow.deletedSections ?? [],
     };
@@ -345,6 +357,7 @@ export async function persistSiteIndex(index: SiteIndex, deletedSections: string
       pages: index.pages,
       sections: index.sections,
       nav: index.nav,
+      tags: index.tags,
       deletedSections,
       updatedAt: now,
     });
@@ -465,6 +478,7 @@ export async function persistAll(
           pages: siteIndex.pages,
           sections: siteIndex.sections,
           nav: siteIndex.nav,
+          tags: siteIndex.tags,
           // Record the deletion INTENT, not just its effect on the order. The
           // restore path reads this back; when it was hardcoded `[]` that path
           // had to re-derive deletions by diffing this snapshot against a fresh

package/src/lib/env.ts

@@ -1,3 +1,5 @@
+// env() is a byte-for-byte twin of packages/platform/src/env.ts: platform cannot
+// import primitives without dragging it into apps/admin's bundle, so keep both.
 declare global {
   interface ImportMeta {
     readonly env?: Record<string, string | undefined>;
@@ -11,3 +13,10 @@ export function env(key: string): string {
     ""
   );
 }
+
+/** Vite replaces `import.meta.env.PROD` with a boolean literal at build time
+ *  (packages are `noExternal`, so that covers this file too), which is why the
+ *  declared string type above is bypassed here. False under Node and vitest. */
+export function isProd(): boolean {
+  return (import.meta.env?.PROD as unknown) === true;
+}

package/src/lib/events.ts

@@ -1,4 +1,4 @@
-import type { NavItem, SiteNav } from "./nav";
+import type { SiteNav } from "./nav";
 
 export interface TypedEvent<T> {
   dispatch(detail: T): void;
@@ -19,7 +19,6 @@ export function createEvent<T>(name: string): TypedEvent<T> {
 }
 
 export const editModeEvent = createEvent<{ isEditMode: boolean }>("editmodechange");
-export const navChangeEvent = createEvent<NavItem[]>("sitenavchange");
 export const darkModeEvent = createEvent<string>("sitedarkmode");
 export const siteNameChangeEvent = createEvent<string>("sitenamechange");
 export const historySelectEvent = createEvent<{ sha: string; date: string }>("history-select");

package/src/lib/image-background.ts

@@ -0,0 +1,31 @@
+import type { CSSProperties } from "react";
+import type { ImageBackground, ImageBackgroundSurface } from "../schemas/shared";
+
+// Class names are spelled out in full so Tailwind's source scan emits them.
+// The surface-light/-dark tokens deliberately do NOT flip under `.dark`: a dark
+// plate chosen for light mode must stay dark. The per-mode switch comes from the
+// `dark:` variant instead, so it follows the theme toggle with no JS. An unset
+// dark mode clears a light-mode plate rather than inheriting it.
+const LIGHT_MODE: Record<ImageBackgroundSurface, string | undefined> = {
+  none: undefined,
+  light: "bg-surface-light",
+  dark: "bg-surface-dark",
+};
+const DARK_MODE: Record<ImageBackgroundSurface, string | undefined> = {
+  none: "dark:bg-transparent",
+  light: "dark:bg-surface-light",
+  dark: "dark:bg-surface-dark",
+};
+
+export interface ImageBackdrop {
+  className?: string;
+  style?: CSSProperties;
+}
+
+export function imageBackdrop(bg: ImageBackground | undefined): ImageBackdrop | undefined {
+  if (!bg) return undefined;
+  if (bg.mode === "custom") return { style: { backgroundColor: bg.color } };
+  const light = LIGHT_MODE[bg.light];
+  if (!light && bg.dark === "none") return undefined;
+  return { className: [light, DARK_MODE[bg.dark]].filter(Boolean).join(" ") };
+}

package/src/lib/index.ts

@@ -4,6 +4,9 @@ export { audiencePasses } from "./pages";
 export { resolveChatbotName, resolveThinkingPhrases, DEFAULT_CHATBOT_NAME } from "./chatbot";
 export { generateNavLinks, toSectionId, type NavItem } from "./nav";
 export { navEntries, pagesInNavOrder, groupOfPage, groupDisplayLabel, reconcileNav } from "./nav-tree";
+export { siteTags, tagDisplayLabel, reconcileTags } from "./tags";
+export { resolveReference, type ReferenceContent } from "./references";
+export { REFERENCE_TYPE } from "./reference-type";
 export {
   deriveContrast,
   contrastColor,
@@ -15,12 +18,11 @@ export {
 } from "./contrast";
 export { primaryVarValue, accentVarValue, onPrimaryVarValue } from "./theme-vars";
 export { sanitizeHtml, ensureSanitizer } from "./sanitize";
-export { gridColsClass } from "./grid";
 export { getIcon, curatedIcons, type IconEntry } from "./icons";
 export { buildGoogleFontsUrl } from "./google-fonts";
 export { formatTimestamp } from "./timestamp";
-export { safeRedirect } from "./safeRedirect";
-export { createEvent, editModeEvent, navChangeEvent, darkModeEvent, type TypedEvent } from "./events";
+export { safeRedirect } from "./safe-redirect";
+export { createEvent, editModeEvent, darkModeEvent, type TypedEvent } from "./events";
 export {
   createRegistry,
   defineSection,
@@ -42,7 +44,6 @@ export {
 export {
   mergeSiteContent,
   loadStaticSiteContent,
-  loadSiteContent,
   type LoadedSection,
   type SiteContent,
 } from "./loader";

package/src/lib/loader.ts

@@ -4,10 +4,14 @@ import { getAllSchemas } from "./registry";
 import { blockDepth, MAX_BLOCK_DEPTH } from "../schemas/block";
 import { upgradeLegacySection } from "./migrate-sections-transform";
 import { NavEntrySchema, type NavEntry } from "../schemas/nav";
+import { TagEntrySchema, type TagEntry } from "../schemas/tags";
 
 export interface LoadedSection {
   section: Section;
   meta: SectionMeta;
+  /** Set only on render-time copies a Reference pulled in (resolveReference):
+   *  the id of that Reference. Never loaded or persisted. */
+  referencedBy?: string;
 }
 
 export interface SiteContent {
@@ -19,6 +23,9 @@ export interface SiteContent {
    *  nav.json from a degraded read permanently destroys the entries this
    *  version dropped. */
   navDegraded: boolean;
+  /** Same contract as navDegraded, for tags.json: a degraded read is
+   *  read-only for tags. */
+  tagsDegraded: boolean;
 }
 
 /**
@@ -34,7 +41,7 @@ function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolea
   if (!navFile) return { entries: [], degraded: false };
   const rawEntries = (navFile as { entries?: unknown }).entries;
   if (!Array.isArray(rawEntries)) {
-    console.warn("Invalid nav.json, falling back to a flat navigation");
+    console.warn("[loader] Invalid nav.json, falling back to a flat navigation");
     return { entries: [], degraded: true };
   }
   const entries: NavEntry[] = [];
@@ -45,11 +52,46 @@ function parseNavFile(navFile: unknown): { entries: NavEntry[]; degraded: boolea
     else dropped++;
   }
   if (dropped > 0) {
-    console.warn(`nav.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; navigation is degraded`);
+    console.warn(`[loader] nav.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; navigation is degraded`);
   }
   return { entries, degraded: dropped > 0 };
 }
 
+/**
+ * Parse the tags.json sidecar with parseNavFile's per-entry tolerance and the
+ * same `degraded` contract. Assignments to deleted sections are NOT pruned
+ * here — that is reconcileTags' job on every read (siteTags), so the runtime
+ * field stays a faithful copy of the file.
+ */
+function parseTagsFile(tagsFile: unknown): { tags: TagEntry[]; degraded: boolean } {
+  if (!tagsFile) return { tags: [], degraded: false };
+  const rawTags = (tagsFile as { tags?: unknown }).tags;
+  if (!Array.isArray(rawTags)) {
+    console.warn("[loader] Invalid tags.json, falling back to no tags");
+    return { tags: [], degraded: true };
+  }
+  const tags: TagEntry[] = [];
+  let dropped = 0;
+  for (const raw of rawTags) {
+    const result = TagEntrySchema.safeParse(raw);
+    if (result.success) tags.push(result.data);
+    else dropped++;
+  }
+  if (dropped > 0) {
+    console.warn(`[loader] tags.json: dropped ${dropped} entr${dropped === 1 ? "y" : "ies"} this package version cannot represent; tags are degraded`);
+  }
+  return { tags, degraded: dropped > 0 };
+}
+
+/**
+ * Whether a load looked for tags.json. Not loaded ⇒ no `index.tags` is attached
+ * and writers leave the file alone; loaded ⇒ `file` is its parsed contents,
+ * with null/undefined meaning absent (an empty registry). Unlike nav, the
+ * difference is load-bearing — an attached `[]` that a writer saves back
+ * deletes every tag — hence an explicit flag rather than undefined-vs-null.
+ */
+export type TagsSidecar = { loaded: false } | { loaded: true; file: unknown };
+
 /**
  * Merge a validated index with raw section file contents.
  * Validates each section file against its Zod schema.
@@ -59,6 +101,7 @@ export function mergeSiteContent(
   index: SiteIndex,
   sectionFiles: Record<string, unknown>,
   navFile?: unknown,
+  tagsSidecar: TagsSidecar = { loaded: false },
 ): SiteContent {
   const sections: LoadedSection[] = [];
 
@@ -112,7 +155,13 @@ export function mergeSiteContent(
   }
 
   const nav = parseNavFile(navFile);
-  return { sections, index: { ...index, nav: nav.entries }, navDegraded: nav.degraded };
+  const tags = tagsSidecar.loaded ? parseTagsFile(tagsSidecar.file) : null;
+  return {
+    sections,
+    index: { ...index, nav: nav.entries, ...(tags ? { tags: tags.tags } : {}) },
+    navDegraded: nav.degraded,
+    tagsDegraded: tags?.degraded ?? false,
+  };
 }
 
 /**
@@ -124,6 +173,7 @@ export function loadStaticSiteContent(
   index: SiteIndex,
   sectionGlob: Record<string, unknown>,
   navFile?: unknown,
+  tagsSidecar: TagsSidecar = { loaded: false },
 ): SiteContent {
   const sectionFiles: Record<string, unknown> = {};
   for (const [path, data] of Object.entries(sectionGlob)) {
@@ -131,56 +181,5 @@ export function loadStaticSiteContent(
     const id = filename.replace(".json", "");
     sectionFiles[id] = data;
   }
-  return mergeSiteContent(index, sectionFiles, navFile);
-}
-
-/**
- * Load site content from the filesystem.
- * For use in scripts and tests — Astro pages should use import.meta.glob instead.
- */
-export async function loadSiteContent(contentDir: string): Promise<SiteContent> {
-  const fs = await import("node:fs/promises");
-  const path = await import("node:path");
-
-  const indexPath = path.join(contentDir, "index.json");
-  const indexRaw = JSON.parse(await fs.readFile(indexPath, "utf-8"));
-  const index = IndexSchema.parse(indexRaw);
-
-  const sectionFiles: Record<string, unknown> = {};
-  for (const id of index.pages.flatMap((p: SiteIndex["pages"][number]) => p.order)) {
-    const sectionPath = path.join(contentDir, "sections", `${id}.json`);
-    sectionFiles[id] = JSON.parse(await fs.readFile(sectionPath, "utf-8"));
-  }
-
-  // nav.json is an optional sidecar — absent (every portal predating page
-  // groups) or unreadable must degrade to a flat nav, never fail the load.
-  //
-  // ABSENT and UNREADABLE are not the same answer, though: absent is the normal
-  // case and safe to overwrite, while a present-but-unparseable sidecar holds
-  // groups this load cannot see. Collapsing both to `undefined` reported
-  // navDegraded: false, so the next nav-touching save wholesale-wrote a flat
-  // nav.json over a file that was still hand-recoverable. Mirrors the
-  // GitHub-backed loader's navRaw/navFile split in @drawnagency/core.
-  let navRaw: string | undefined;
-  let readFailed = false;
-  try {
-    navRaw = await fs.readFile(path.join(contentDir, "nav.json"), "utf-8");
-  } catch (err) {
-    // Only a genuinely missing file is "absent". A permissions/IO error leaves
-    // the sidecar's contents unknown, which must not license overwriting it.
-    readFailed = (err as { code?: string })?.code !== "ENOENT";
-  }
-
-  let navFile: unknown;
-  let parseFailed = false;
-  if (navRaw !== undefined) {
-    try {
-      navFile = JSON.parse(navRaw);
-    } catch {
-      parseFailed = true;
-    }
-  }
-
-  const content = mergeSiteContent(index, sectionFiles, navFile);
-  return readFailed || parseFailed ? { ...content, navDegraded: true } : content;
+  return mergeSiteContent(index, sectionFiles, navFile, tagsSidecar);
 }

package/src/lib/nav-tree.ts

@@ -204,3 +204,74 @@ export function moveNavEntry(index: SiteIndex, from: NavLocation, to: NavLocatio
 
   return withNav(index, entries);
 }
+
+/**
+ * "Moved <label> to position N of M" for the aria-live reorder announcement,
+ * covering both `moveNavEntry` callers: drag (PagesModal/NavGroupRow) and the
+ * Move up/down buttons. `prevIndex` resolves WHO moved and its label (read
+ * before the move, since `from` is a position, not an id); `nextIndex` (the
+ * result of `moveNavEntry(prevIndex, from, to)`) is searched by id for where
+ * it actually landed — robust to `moveNavEntry`'s own clamping, so the caller
+ * never has to replicate that math. Returns null if `from` didn't resolve to
+ * a real row (defensive; ordinary callers always pass a live location).
+ */
+/** A top-level entry counts toward "N of M" iff it's a group (always visible)
+ *  or a page that isn't archived — mirrors the PagesModal Move up/down rows,
+ *  which skip archived pages entirely rather than render an inert slot. */
+function isLiveTopEntry(index: SiteIndex, entry: NavEntry): boolean {
+  if (entry.kind === "group") return true;
+  const page = index.pages.find((p) => p.id === entry.pageId);
+  return page?.status === "live";
+}
+
+export function describeNavMove(prevIndex: SiteIndex, nextIndex: SiteIndex, from: NavLocation): string | null {
+  const prevEntries = navEntries(prevIndex);
+  let label: string;
+  let pageId: string | null = null;
+  let groupId: string | null = null;
+
+  if (from.groupId === null) {
+    const entry = prevEntries[from.index];
+    if (!entry) return null;
+    if (entry.kind === "group") {
+      label = groupDisplayLabel(entry.label);
+      groupId = entry.id;
+    } else {
+      const page = prevIndex.pages.find((p) => p.id === entry.pageId);
+      if (!page) return null;
+      label = page.title || "Untitled";
+      pageId = page.id;
+    }
+  } else {
+    const group = prevEntries.find((e) => e.kind === "group" && e.id === from.groupId);
+    if (!group || group.kind !== "group") return null;
+    const id = group.pageIds[from.index];
+    if (!id) return null;
+    const page = prevIndex.pages.find((p) => p.id === id);
+    if (!page) return null;
+    label = page.title || "Untitled";
+    pageId = page.id;
+  }
+
+  const nextEntries = navEntries(nextIndex);
+  const liveTopEntries = nextEntries.filter((e) => isLiveTopEntry(nextIndex, e));
+
+  if (groupId !== null) {
+    const i = liveTopEntries.findIndex((e) => e.kind === "group" && e.id === groupId);
+    if (i === -1) return null;
+    return `Moved ${label} to position ${i + 1} of ${liveTopEntries.length}`;
+  }
+
+  if (pageId === null) return null;
+
+  const topIndex = liveTopEntries.findIndex((e) => e.kind === "page" && e.pageId === pageId);
+  if (topIndex !== -1) return `Moved ${label} to position ${topIndex + 1} of ${liveTopEntries.length}`;
+  for (const e of nextEntries) {
+    if (e.kind === "group") {
+      const liveMemberIds = e.pageIds.filter((id) => nextIndex.pages.find((p) => p.id === id)?.status === "live");
+      const gi = liveMemberIds.indexOf(pageId);
+      if (gi !== -1) return `Moved ${label} to position ${gi + 1} of ${liveMemberIds.length}`;
+    }
+  }
+  return null;
+}