@drawnagency/primitives 0.1.66 → 0.1.68

package/src/components/chat/ChatPanel.tsx

@@ -0,0 +1,152 @@
+import { useRef, useState } from "react";
+import { cn } from "../../lib/cn";
+
+export interface ChatMessage { role: "user" | "assistant"; content: string }
+
+const SESSION_KEY = "bp-chat-session";
+
+function sessionId(): string {
+  let id = window.localStorage.getItem(SESSION_KEY);
+  if (!id) {
+    id = crypto.randomUUID();
+    window.localStorage.setItem(SESSION_KEY, id);
+  }
+  return id;
+}
+
+const ERROR_COPY: Record<string, string> = {
+  rate_limited: "You've hit the message limit — try again in a minute.",
+  disabled: "Chat isn't available right now.",
+  not_authorized: "You don't have access to chat on this site.",
+  upstream_error: "Something went wrong — please try again.",
+};
+
+/** Parse our /api/chat SSE frames out of a fetch body. Exported for tests. */
+export async function streamChat(
+  body: { messages: ChatMessage[]; sessionId: string; taskId?: string; draftChatbot?: unknown },
+  onText: (text: string) => void,
+): Promise<{ ok: true; truncated: boolean } | { ok: false; error: string; retryAfterMs?: number }> {
+  try {
+    const res = await fetch("/api/chat", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok || !res.body) {
+      const err = await res.json().catch(() => ({ error: "upstream_error" }));
+      return { ok: false, error: err.error ?? "upstream_error", retryAfterMs: err.retryAfterMs };
+    }
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    let truncated = false;
+    let errored: string | null = null;
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let sep: number;
+      while ((sep = buffer.indexOf("\n\n")) !== -1) {
+        const frame = buffer.slice(0, sep);
+        buffer = buffer.slice(sep + 2);
+        const event = /^event: (.+)$/m.exec(frame)?.[1];
+        const dataRaw = /^data: (.+)$/m.exec(frame)?.[1];
+        if (!event || !dataRaw) continue;
+        try {
+          const data = JSON.parse(dataRaw);
+          if (event === "text") onText(data.text);
+          else if (event === "done") truncated = data.truncated === true;
+          else if (event === "error") errored = data.error ?? "upstream_error";
+        } catch { /* malformed frame — skip */ }
+      }
+    }
+    return errored ? { ok: false, error: errored } : { ok: true, truncated };
+  } catch {
+    // Network failure or a mid-stream reader rejection (upstream abort) — never
+    // let this propagate out of send(), or `busy` sticks true forever.
+    return { ok: false, error: "upstream_error" };
+  }
+}
+
+export default function ChatPanel({ open, onClose, siteName, tasks, isEditor, draftChatbot }: {
+  open: boolean;
+  onClose: () => void;
+  siteName: string;
+  tasks: { id: string; label: string }[];
+  isEditor?: boolean;
+  /** Set only by the configurator's test panel. */
+  draftChatbot?: unknown;
+}) {
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [taskId, setTaskId] = useState<string>("");
+  const [input, setInput] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const streamingRef = useRef("");
+
+  async function send() {
+    const text = input.trim();
+    if (!text || busy) return;
+    setNotice(null);
+    setInput("");
+    setBusy(true);
+    const history: ChatMessage[] = [...messages, { role: "user", content: text }];
+    setMessages([...history, { role: "assistant", content: "" }]);
+    streamingRef.current = "";
+    const result = await streamChat(
+      { messages: history, sessionId: sessionId(), ...(taskId ? { taskId } : {}), ...(draftChatbot !== undefined ? { draftChatbot } : {}) },
+      (delta) => {
+        streamingRef.current += delta;
+        const streamed = streamingRef.current;
+        setMessages([...history, { role: "assistant", content: streamed }]);
+      },
+    );
+    setBusy(false);
+    if (!result.ok) {
+      setMessages(history); // drop the empty assistant stub
+      setNotice(ERROR_COPY[result.error] ?? ERROR_COPY.upstream_error);
+    } else if (result.truncated) {
+      setNotice("Some brand content didn't fit — answers may be incomplete.");
+    }
+  }
+
+  if (!open) return null;
+
+  return (
+    <div role="dialog" aria-label={`Chat with ${siteName}`}
+      className="fixed bottom-20 right-4 z-40 flex h-[28rem] w-80 flex-col rounded-lg border border-base-200 bg-base shadow-xl">
+      <div className="flex items-center justify-between gap-2 border-b border-base-200 px-3 py-2">
+        <span className="text-sm font-medium text-base-contrast">{siteName} assistant</span>
+        {tasks.length > 0 && (
+          <select aria-label="Task" value={taskId} onChange={(e) => setTaskId(e.target.value)}
+            className="max-w-36 rounded border border-base-200 bg-base-accent px-1 py-0.5 text-xs">
+            <option value="">General</option>
+            {tasks.map((t) => <option key={t.id} value={t.id}>{t.label}</option>)}
+          </select>
+        )}
+        <button type="button" aria-label="Close chat" onClick={onClose} className="text-base-contrast-light hover:text-base-contrast">×</button>
+      </div>
+      <div className="flex-1 space-y-2 overflow-y-auto p-3">
+        {messages.map((m, i) => (
+          <div key={i} className={cn("max-w-[85%] whitespace-pre-wrap rounded-lg px-3 py-2 text-sm",
+            m.role === "user" ? "ml-auto bg-primary text-primary-contrast" : "bg-base-accent text-base-contrast")}>
+            {m.content || (busy && i === messages.length - 1 ? "…" : m.content)}
+          </div>
+        ))}
+        {notice && <p className="text-xs text-base-contrast-light">{notice}</p>}
+      </div>
+      <form className="flex gap-2 border-t border-base-200 p-2" onSubmit={(e) => { e.preventDefault(); void send(); }}>
+        <input
+          value={input}
+          onChange={(e) => setInput(e.target.value)}
+          placeholder={`Ask about ${siteName}…`}
+          maxLength={4000}
+          className="min-w-0 flex-1 rounded border border-base-200 bg-base px-2 py-1 text-sm text-base-contrast"
+        />
+        <button type="submit" aria-label="Send" disabled={busy}
+          className="rounded bg-primary px-3 py-1 text-sm text-primary-contrast disabled:opacity-50">→</button>
+      </form>
+      {isEditor && <p className="border-t border-base-200 px-3 py-1 text-[10px] text-base-contrast-light">Editor view — answers ground on published content.</p>}
+    </div>
+  );
+}

package/src/components/chat/ChatWidget.tsx

@@ -0,0 +1,38 @@
+// Viewer-facing chat launcher. Renders ONLY the floating button until first
+// open; the panel (and its code) loads lazily so viewers who never click pay
+// almost nothing. Browser-safe: no node imports, no process.env.
+import { lazy, Suspense, useState } from "react";
+
+const ChatPanel = lazy(() => import("./ChatPanel"));
+
+export interface ChatWidgetProps {
+  siteName: string;
+  /** Already audience-filtered server-side — never pass unfiltered config tasks. */
+  tasks: { id: string; label: string }[];
+  isEditor?: boolean;
+}
+
+export default function ChatWidget({ siteName, tasks, isEditor }: ChatWidgetProps) {
+  const [open, setOpen] = useState(false);
+  const [everOpened, setEverOpened] = useState(false);
+
+  return (
+    <>
+      <button
+        type="button"
+        aria-label={`Chat with ${siteName}`}
+        onClick={() => { setOpen((o) => !o); setEverOpened(true); }}
+        className="fixed bottom-4 right-4 z-40 flex h-12 w-12 items-center justify-center rounded-full bg-primary text-primary-contrast shadow-lg hover:opacity-90 transition-opacity"
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" className="h-6 w-6" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+          <path d="M7.9 20A9 9 0 1 0 4 16.1L2 22Z" />
+        </svg>
+      </button>
+      {everOpened && (
+        <Suspense fallback={null}>
+          <ChatPanel open={open} onClose={() => setOpen(false)} siteName={siteName} tasks={tasks} isEditor={isEditor} />
+        </Suspense>
+      )}
+    </>
+  );
+}

package/src/components/primitives/defineHeadingSection.tsx

@@ -15,6 +15,8 @@ interface HeadingSectionConfig<T extends string> {
   defaultHeading: string;
   /** When true, adds the `excludeFromNav` content field plus its settings toggle. */
   navExclusion?: boolean;
+  /** Per-type authoring note surfaced by get_section_schema. */
+  authoringNote: string;
 }
 
 /**
@@ -24,9 +26,22 @@ interface HeadingSectionConfig<T extends string> {
  * shared HeadingSection primitive through the identical edit/view plumbing.
  */
 export function defineHeadingSection<T extends string>(config: HeadingSectionConfig<T>) {
+  const heading = z
+    .string()
+    .describe(
+      "The heading text. Plain text, one line; keep concise — it appears verbatim in the on-page heading and (unless excluded) the navigation.",
+    );
   const content = config.navExclusion
-    ? z.object({ heading: z.string(), excludeFromNav: z.boolean().optional() })
-    : z.object({ heading: z.string() });
+    ? z.object({
+        heading,
+        excludeFromNav: z
+          .boolean()
+          .describe(
+            "When true, this heading is omitted from the generated navigation tree while still rendering on the page.",
+          )
+          .optional(),
+      })
+    : z.object({ heading });
   const schema = z.object({ type: z.literal(config.type), content });
 
   return defineSection({
@@ -35,6 +50,7 @@ export function defineHeadingSection<T extends string>(config: HeadingSectionCon
     icon: config.icon,
     schema,
     navRole: config.navRole,
+    authoringNote: config.authoringNote,
     component: ({ content, onChange }) => (
       <HeadingSection
         heading={content.content.heading}

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

@@ -7,9 +7,14 @@ import CTAButton from "./CTAButton";
 const schema = z.object({
   type: z.literal("button"),
   content: z.object({
-    text: z.string(),
-    link: LinkValueSchema.optional(),
-    download: z.boolean().optional(),
+    text: z.string().describe("The button label. Plain text, short (a few words)."),
+    link: LinkValueSchema.describe(
+      "Where the button points — an internal page or a safe external URL.",
+    ).optional(),
+    download: z
+      .boolean()
+      .describe("When true, the link is treated as a file download rather than navigation.")
+      .optional(),
   }),
 });
 
@@ -18,6 +23,8 @@ export default defineSection({
   label: "Button",
   icon: <RectangleHorizontal size={18} />,
   schema,
+  authoringNote:
+    "A call-to-action button linking to an internal page or external URL, optionally as a file download. Use for a single prominent action.",
   component: ({ content, onChange }) => (
     <CTAButton
       text={content.content.text}

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

@@ -7,13 +7,19 @@ import { pluralize } from "../../../lib/text";
 
 const schema = z.object({
   type: z.literal("colors"),
-  content: z.object({ colors: z.array(ColorItemSchema) }),
-  options: z.object({
-    label: z.string().optional(),
-    columns: z.number().int().min(2).max(4).optional(),
-    collapsing: z.boolean().optional(),
-    showLabel: z.boolean().optional(),
-  }).optional(),
+  content: z.object({
+    colors: z
+      .array(ColorItemSchema)
+      .describe("The list of brand colors, each with one or more color-space values (hex/rgb/cmyk/pantone)."),
+  }),
+  options: z
+    .object({
+      label: z.string().describe("Optional heading shown above the palette.").optional(),
+      columns: z.number().int().min(2).max(4).describe("Number of swatch columns (2–4).").optional(),
+      collapsing: z.boolean().describe("When true, use the compact collapsing swatch layout.").optional(),
+      showLabel: z.boolean().describe("When true, show the palette label.").optional(),
+    })
+    .optional(),
 });
 
 export default defineSection({
@@ -22,6 +28,8 @@ export default defineSection({
   label: "Colors",
   icon: <Palette size={18} />,
   schema,
+  authoringNote:
+    "A brand color palette. Each color may carry hex/rgb/cmyk/pantone values. Use to document brand colors with swatches.",
   component: ({ content, options, onChange, openModal }) => (
     <Colors
       colors={content.content.colors}

package/src/components/sections/Colors/schema.ts

@@ -17,8 +17,11 @@ export const ColorSpaceSchema = z.object({
 export type ColorSpace = z.infer<typeof ColorSpaceSchema>;
 
 export const ColorItemSchema = z.object({
-  name: z.string().optional(),
-  spaces: z.array(ColorSpaceSchema).min(1),
+  name: z.string().describe("Optional display name for this color (e.g. 'Brand Primary').").optional(),
+  spaces: z
+    .array(ColorSpaceSchema)
+    .describe("One or more color-space definitions (hex/rgb/cmyk/pantone) for this color.")
+    .min(1),
 });
 
 export type ColorItem = z.infer<typeof ColorItemSchema>;

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

@@ -11,9 +11,23 @@ const schema = z.object({
   type: z.literal("container"),
   content: z
     .object({
-      columns: z.number().int().min(1).max(MAX_CONTAINER_COLUMNS).default(1),
-      flow: z.enum(["row", "column"]).default("row"),
-      childDefaults: z.record(z.string(), z.unknown()).optional(),
+      columns: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_CONTAINER_COLUMNS)
+        .describe("Number of columns in the grid. Children flow across this many columns.")
+        .default(1),
+      flow: z
+        .enum(["row", "column"])
+        .describe(
+          "Layout direction: 'row' (children flow left-to-right across columns) or 'column' (stacked).",
+        )
+        .default("row"),
+      childDefaults: z
+        .record(z.string(), z.unknown())
+        .describe("Optional default option values applied to child sections (inheritable settings only).")
+        .optional(),
       // Recursive: children are full blocks. z.lazy defers evaluation to parse
       // time, by which point every section schema (incl. container) is registered.
       children: z.array(z.lazy(() => getSectionSchema())).default([]),
@@ -37,6 +51,8 @@ export default defineSection({
   label: "Container",
   icon: <LayoutTemplate size={18} />,
   schema,
+  authoringNote:
+    "A layout wrapper that arranges child sections into columns/rows. Use to place blocks side by side or build multi-column layouts; set columns and add children.",
   component: ({ content, onChange, isEditMode, openModal }) => (
     <Container content={content as never} isEditMode={!!isEditMode} onChange={onChange as never} openModal={openModal} />
   ),

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

@@ -8,16 +8,25 @@ import { DoDontMediaBlock } from "./DoDontMediaBlock";
 const schema = z.object({
   type: z.literal("dodont_media"),
   content: z.object({
-    ref: SingleMediaReferenceSchema,
-    link: LinkValueSchema.optional(),
-    dodont: z.enum(["do", "dont"]),
+    ref: SingleMediaReferenceSchema.describe(
+      "The image or video asset to display (a media reference by id). Required.",
+    ),
+    link: LinkValueSchema.describe(
+      "Optional link wrapping the media — an internal page or a safe external URL.",
+    ).optional(),
+    dodont: z
+      .enum(["do", "dont"])
+      .describe("Whether this is a 'do' (correct) or 'dont' (incorrect) example."),
   }),
   options: z
     .object({
-      square: z.boolean().optional(),
-      showCaption: z.boolean().optional(),
-      border: z.boolean().optional(),
-      objectFit: z.enum(["cover", "contain"]).optional(),
+      square: z.boolean().describe("When true, crop the media to a 1:1 square aspect ratio.").optional(),
+      showCaption: z.boolean().describe("When true, render the asset's caption beneath it.").optional(),
+      border: z.boolean().describe("When true, draw a border around the media.").optional(),
+      objectFit: z
+        .enum(["cover", "contain"])
+        .describe("How the image fills its box: 'contain' (fit whole image) or 'cover' (fill and crop).")
+        .optional(),
     })
     .default({}),
 });
@@ -28,6 +37,8 @@ export default defineSection({
   category: "brand-guide",
   icon: <ImageIcon size={18} />,
   schema,
+  authoringNote:
+    "A single image or video tagged as a 'do' or 'don't' example. Use inside a Container to build side-by-side do/don't comparisons of visual usage.",
   component: ({ content, options, onChange }) => (
     <DoDontMediaBlock
       refValue={content.content.ref}

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

@@ -16,6 +16,7 @@ interface Props {
   icon?: string | null;
   showLabel?: boolean;
   stackText?: boolean;
+  dodont?: "do" | "dont";
   labelClassName?: string;
   textClassName?: string;
   iconClassName?: string;
@@ -28,6 +29,7 @@ export default function IconList({
   icon = null,
   showLabel = true,
   stackText = false,
+  dodont,
   labelClassName = "font-bold text-base-contrast",
   textClassName = "text-base-contrast-light",
   iconClassName = "text-primary",
@@ -41,11 +43,11 @@ export default function IconList({
       onChange?.({
         type: "icon_list",
         content: { items: newItems },
-        options: { icon, showLabel, stackText },
+        options: { icon, showLabel, stackText, dodont },
       });
       onItemsChange?.(newItems);
     },
-    [onChange, onItemsChange, icon, showLabel, stackText],
+    [onChange, onItemsChange, icon, showLabel, stackText, dodont],
   );
 
   if (!isEditMode) {
@@ -55,6 +57,7 @@ export default function IconList({
         defaultIcon={icon}
         showLabel={showLabel}
         stackText={stackText}
+        dodont={dodont}
         labelClassName={labelClassName}
         textClassName={textClassName}
         iconClassName={iconClassName}
@@ -68,6 +71,7 @@ export default function IconList({
       defaultIcon={icon}
       showLabel={showLabel}
       stackText={stackText}
+      dodont={dodont}
       labelClassName={labelClassName}
       textClassName={textClassName}
       iconClassName={iconClassName}
@@ -80,18 +84,32 @@ export default function IconList({
 // Resolve the effective icon for an item: per-item override > section default
 // ---------------------------------------------------------------------------
 
-function resolveIcon(item: IconListItem, defaultIcon: string | null | undefined) {
-  // dodont WINS over item.icon and the section default — forces the DoDontList glyph.
+function resolveIcon(
+  item: IconListItem,
+  defaultIcon: string | null | undefined,
+  sectionDodont: "do" | "dont" | undefined,
+) {
+  // Precedence: per-item tag > per-item icon > whole-list default > section default icon.
   if (item.dodont === "do") return getIcon("check") ?? null;
   if (item.dodont === "dont") return getIcon("x") ?? null;
-  const id = item.icon ?? defaultIcon;
-  return id ? getIcon(id) : null;
+  if (item.icon) return getIcon(item.icon) ?? null;
+  if (sectionDodont === "do") return getIcon("check") ?? null;
+  if (sectionDodont === "dont") return getIcon("x") ?? null;
+  return defaultIcon ? getIcon(defaultIcon) : null;
 }
 
-// Per-item icon color: green for "do", red for "dont", else the section-wide class.
-function resolveIconColor(item: IconListItem, iconClassName: string) {
+// Per-item icon color: green for "do", red for "dont" (item tag then whole-list
+// default), else the section-wide class. Mirrors resolveIcon's precedence.
+function resolveIconColor(
+  item: IconListItem,
+  iconClassName: string,
+  sectionDodont: "do" | "dont" | undefined,
+) {
   if (item.dodont === "do") return "text-green-600";
   if (item.dodont === "dont") return "text-red-600";
+  if (item.icon) return iconClassName;
+  if (sectionDodont === "do") return "text-green-600";
+  if (sectionDodont === "dont") return "text-red-600";
   return iconClassName;
 }
 
@@ -104,6 +122,7 @@ function ViewIconList({
   defaultIcon,
   showLabel,
   stackText,
+  dodont,
   labelClassName,
   textClassName,
   iconClassName,
@@ -112,17 +131,18 @@ function ViewIconList({
   defaultIcon: string | null | undefined;
   showLabel: boolean;
   stackText: boolean;
+  dodont: "do" | "dont" | undefined;
   labelClassName: string;
   textClassName: string;
   iconClassName: string;
 }) {
-  const hasAnyIcon = items.some((item) => resolveIcon(item, defaultIcon));
+  const hasAnyIcon = items.some((item) => resolveIcon(item, defaultIcon, dodont));
 
   return (
     <div className="grid gap-4 pb-4">
       {items.map((item, i) => {
-        const iconEntry = resolveIcon(item, defaultIcon);
-        const iconColor = resolveIconColor(item, iconClassName);
+        const iconEntry = resolveIcon(item, defaultIcon, dodont);
+        const iconColor = resolveIconColor(item, iconClassName, dodont);
         return (
           <div
             key={i}
@@ -164,6 +184,7 @@ function EditIconList({
   defaultIcon,
   showLabel,
   stackText,
+  dodont,
   labelClassName,
   textClassName,
   iconClassName,
@@ -173,6 +194,7 @@ function EditIconList({
   defaultIcon: string | null | undefined;
   showLabel: boolean;
   stackText: boolean;
+  dodont: "do" | "dont" | undefined;
   labelClassName: string;
   textClassName: string;
   iconClassName: string;
@@ -228,6 +250,7 @@ function EditIconList({
           hasAnyIcon={hasAnyIcon}
           showLabel={showLabel}
           stackText={stackText}
+          dodont={dodont}
           labelClassName={labelClassName}
           textClassName={textClassName}
           iconClassName={iconClassName}
@@ -268,6 +291,7 @@ function EditableRow({
   hasAnyIcon,
   showLabel,
   stackText,
+  dodont,
   labelClassName,
   textClassName,
   iconClassName,
@@ -285,6 +309,7 @@ function EditableRow({
   hasAnyIcon: boolean;
   showLabel: boolean;
   stackText: boolean;
+  dodont: "do" | "dont" | undefined;
   labelClassName: string;
   textClassName: string;
   iconClassName: string;
@@ -302,9 +327,9 @@ function EditableRow({
   const [dodontOpen, setDodontOpen] = useState(false);
   const [editingSuppressed, setEditingSuppressed] = useState(false);
 
-  const iconEntry = resolveIcon(item, defaultIcon);
+  const iconEntry = resolveIcon(item, defaultIcon, dodont);
   const effectiveIconId = item.icon ?? defaultIcon ?? null;
-  const iconColor = resolveIconColor(item, iconClassName);
+  const iconColor = resolveIconColor(item, iconClassName, dodont);
 
   useEffect(() => {
     const row = rowRef.current;
@@ -373,12 +398,11 @@ function EditableRow({
       onMouseMove={() => setEditingSuppressed(false)}
     >
 
-      {/* Icon — matches ViewIconList layout: 24px column, flex items-start pt-0.5.
-          A SINGLE always-present trigger shows the current effective glyph
-          (resolveIcon returns the forced check/x for tagged items) and opens
-          the IconPicker, which carries both the curated grid (None mode) and
-          the Do/Don't tiles (Do-Don't mode). Reachable for every item, tagged
-          or not, so tags can be edited or cleared via the picker. */}
+      {/* Icon cell — matches ViewIconList layout: 24px column, flex items-start
+          pt-0.5. A single always-present trigger shows the current effective glyph
+          (resolveIcon returns the forced check/x for tagged rows or a whole-list
+          default) and opens the IconPicker (a pure icon grid). Per-item do/dont
+          tagging lives in the separate DoDontToggle in the row's hover toolbar. */}
       {hasAnyIcon && (
         <div
           data-testid="icon-list-icon"