@drawnagency/primitives 0.1.66 → 0.1.67

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

@@ -1,6 +1,8 @@
 import { defineSection } from "../../../lib/registry";
 import { z } from "zod";
-import { List } from "lucide-react";
+import { List, Columns2 } from "lucide-react";
+import type { SectionPreset } from "../../../lib/registry";
+import type { SectionContent } from "../../../schemas/sections";
 import IconList from "./IconList";
 import { IconListSettings } from "./IconListSettings";
 import { pluralize } from "../../../lib/text";
@@ -16,27 +18,68 @@ export type IconListItem = z.infer<typeof IconListItemSchema>;
 const schema = z.object({
   type: z.literal("icon_list"),
   content: z.object({
-    items: z.array(IconListItemSchema),
+    items: z
+      .array(IconListItemSchema)
+      .describe(
+        "The list entries. Each item has a label, descriptive text, an optional icon, and an optional do/don't marker.",
+      ),
   }),
-  options: z.object({
-    icon: z.string().nullable().optional(),
-    showLabel: z.boolean().optional(),
-    stackText: z.boolean().optional(),
-  }).optional(),
+  options: z
+    .object({
+      icon: z
+        .string()
+        .nullable()
+        .describe("Default icon name applied to items that don't specify their own; null for no icon.")
+        .optional(),
+      showLabel: z.boolean().describe("When true, render each item's label.").optional(),
+      stackText: z
+        .boolean()
+        .describe("When true, stack the label and text vertically instead of inline.")
+        .optional(),
+      dodont: z
+        .enum(["do", "dont"])
+        .describe("Whole-list do/don't mode: render every item with a green check (do) or red x (don't).")
+        .optional(),
+    })
+    .optional(),
 });
 
+// One-click "Do / Don't list": a 2-column container holding a green-check "Do"
+// icon_list and a red-x "Don't" icon_list, using the whole-list options.dodont
+// default. Same shape the legacy do_dont migration produces. Lives here (brand-guide
+// layer); it reaches the core Add-menu only via SectionDefinition.presets.
+const doDontListPreset: SectionPreset = {
+  id: "do_dont_list",
+  label: "Do / Don't list",
+  icon: <Columns2 size={18} />,
+  build: (newId): SectionContent => ({
+    type: "container",
+    content: {
+      columns: 2,
+      flow: "row",
+      children: [
+        { id: newId(), type: "icon_list", content: { items: [{ label: "", text: "" }] }, options: { dodont: "do" } },
+        { id: newId(), type: "icon_list", content: { items: [{ label: "", text: "" }] }, options: { dodont: "dont" } },
+      ],
+    },
+  }),
+};
+
 export default defineSection({
   type: "icon_list",
   category: "brand-guide",
   label: "Icon List",
   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.",
   component: ({ content, options, onChange }) => (
     <IconList
       items={content.content.items}
       icon={options?.icon as string | null}
       showLabel={options?.showLabel as boolean}
       stackText={options?.stackText as boolean}
+      dodont={options?.dodont as "do" | "dont" | undefined}
       onChange={onChange ? (c) => onChange(c as typeof content) : undefined}
     />
   ),
@@ -46,4 +89,5 @@ export default defineSection({
   }),
   getLabel: (content) => pluralize(content.content.items.length, "icon"),
   settingsForm: IconListSettings,
+  presets: [doDontListPreset],
 });

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

@@ -9,4 +9,6 @@ export default defineHeadingSection({
   tag: "h2",
   placeholder: "Section heading",
   defaultHeading: "New Section",
+  authoringNote:
+    "A top-level section heading (renders an <h2>, reported to navigation as h1). Use it to begin a major named section of the guide; its text becomes a navigation entry.",
 });

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

@@ -8,15 +8,22 @@ import { MediaBlock } from "./MediaBlock";
 const schema = z.object({
   type: z.literal("media"),
   content: z.object({
-    ref: SingleMediaReferenceSchema,
-    link: LinkValueSchema.optional(),
+    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(),
   }),
   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({}),
 });
@@ -26,6 +33,8 @@ export default defineSection({
   label: "Media",
   icon: <ImageIcon size={18} />,
   schema,
+  authoringNote:
+    "A single image or video with optional caption and link. Use to show one asset; for several assets side by side, place multiple Media blocks inside a Container.",
   component: ({ content, options, onChange }) => (
     <MediaBlock
       refValue={content.content.ref}

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

@@ -6,7 +6,13 @@ import { stripHtmlToPlainText, truncate } from "../../../lib/text";
 
 const schema = z.object({
   type: z.literal("prose"),
-  content: z.object({ body: z.string() }),
+  content: z.object({
+    body: z
+      .string()
+      .describe(
+        "Rich-text HTML for the paragraph block. Author with the editor; stored as sanitized HTML.",
+      ),
+  }),
 });
 
 export default defineSection({
@@ -14,6 +20,8 @@ export default defineSection({
   label: "Prose",
   icon: <AlignLeft size={18} />,
   schema,
+  authoringNote:
+    "A block of rich-text body copy (paragraphs, lists, inline emphasis, links). Use for any explanatory prose; author with the editor, not raw HTML.",
   richTextFields: ["body"],
   component: ({ content, onChange }) => (
     <Prose body={content.content.body} onChange={onChange ? (c) => onChange(c as typeof content) : undefined} />

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

@@ -13,6 +13,8 @@ export default defineSection({
   label: "Spacer",
   icon: <SquareDashed size={18} />,
   schema,
+  authoringNote:
+    "Vertical whitespace between sections. Use sparingly to add breathing room where default section spacing is insufficient.",
   component: () => <Spacer />,
   defaults: () => ({ type: "spacer" as const, content: {} }),
 });

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

@@ -10,4 +10,6 @@ export default defineHeadingSection({
   placeholder: "Sub heading",
   defaultHeading: "New Sub Heading",
   navExclusion: true,
+  authoringNote:
+    "A second-level heading (renders <h3>, nav level h2). Use under a Link Heading to divide a section; toggle Exclude from navigation to keep it out of the nav tree.",
 });

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

@@ -10,4 +10,6 @@ export default defineHeadingSection({
   placeholder: "Sub sub heading",
   defaultHeading: "New Sub Sub Heading",
   navExclusion: true,
+  authoringNote:
+    "A third-level heading (renders <h4>, nav level h3). Use for the finest-grained labeled subsection; toggle Exclude from navigation to omit it from the nav tree.",
 });

package/src/components/shell/EditorShell.tsx

@@ -27,6 +27,7 @@ import { SectionTypePicker } from "./SectionTypePicker";
 import { ensureSectionsRegistered } from "../sections/register";
 import { getSection, getAllSections } from "../../lib/registry";
 import { childInsertableTypes, insertChildAt } from "../../lib/container-ops";
+import { buildInsertMenuOptions, resolveInsertedContent } from "../../lib/insert-menu";
 
 ensureSectionsRegistered();
 import { BugReportFAB } from "./BugReportFAB";
@@ -591,13 +592,16 @@ export default function EditorShell({
   );
 
   const onAddSection = useCallback(
-    (insertIndex: number, type: string) => {
-      const definition = getSection(type);
-      if (!definition || !resolvedActivePage) return;
-      const id = typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
-        ? crypto.randomUUID() : `_id_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-      const content = definition.defaults() as object;
-      const meta = { type, status: "draft" as const, access: [] as string[] };
+    (insertIndex: number, selection: string) => {
+      if (!resolvedActivePage) return;
+      const newId = () =>
+        typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+          ? crypto.randomUUID()
+          : `_id_${Date.now()}_${Math.random().toString(36).slice(2)}`;
+      const content = resolveInsertedContent(selection, getAllSections(), newId);
+      if (!content) return;
+      const id = newId();
+      const meta = { type: content.type, status: "draft" as const, access: [] as string[] };
       const newSection: LoadedSection = { section: { id, ...content } as LoadedSection["section"], meta };
 
       setSections((prev) => [...prev, newSection]);
@@ -1189,7 +1193,7 @@ function EditorContent({
   dirtySectionIds: Set<string>;
   isPublishing: boolean;
   onSectionChange: (sectionId: string, content: SectionContent) => void;
-  onAddSection: (insertIndex: number, type: string) => void;
+  onAddSection: (insertIndex: number, selection: string) => void;
   onDeleteSection: (sectionId: string) => void;
   onReorderSections: (fromIndex: number, toIndex: number) => void;
   onBlockMove: (move: BlockMove) => void;
@@ -1205,17 +1209,7 @@ function EditorContent({
   const [pendingInsertIndex, setPendingInsertIndex] = useState<number | null>(null);
   const dismissPendingInsert = useCallback(() => setPendingInsertIndex(null), []);
 
-  const typeOptions = useMemo(
-    () =>
-      getAllSections()
-        .filter((def) => def.type !== "spacer")
-        .map((def) => ({
-          type: def.type,
-          label: def.label,
-          icon: def.icon,
-        })),
-    [],
-  );
+  const typeOptions = useMemo(() => buildInsertMenuOptions(getAllSections()), []);
 
   const editingEnabled = isEditMode && !isPublishing;
 

package/src/lib/insert-menu.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+import type { SectionDefinition } from "./registry";
+import type { SectionContent } from "../schemas/sections";
+
+/** Namespacing prefix for preset selections in the Add-section menu. */
+export const PRESET_PREFIX = "__preset:";
+
+/** One Add-section menu entry: a section `type`, or `__preset:<presetId>`. */
+export interface InsertMenuOption {
+  type: string;
+  label: string;
+  icon?: ReactNode;
+}
+
+/** Every non-spacer section type, followed by presets contributed by registered
+ *  sections. Presets appear only when their owning section is registered, so a
+ *  core-only build (no brand-guide sections) shows no brand-guide presets. */
+export function buildInsertMenuOptions(sections: SectionDefinition[]): InsertMenuOption[] {
+  const typeOptions = sections
+    .filter((def) => def.type !== "spacer")
+    .map((def) => ({ type: def.type, label: def.label, icon: def.icon }));
+  const presetOptions = sections
+    .flatMap((def) => def.presets ?? [])
+    .map((p) => ({ type: `${PRESET_PREFIX}${p.id}`, label: p.label, icon: p.icon }));
+  return [...typeOptions, ...presetOptions];
+}
+
+/** Resolve an Add-menu selection to ready-to-insert content. `newId` mints ids for
+ *  any nested children a preset creates. Returns null for an unknown type/preset. */
+export function resolveInsertedContent(
+  selection: string,
+  sections: SectionDefinition[],
+  newId: () => string,
+): SectionContent | null {
+  if (selection.startsWith(PRESET_PREFIX)) {
+    const id = selection.slice(PRESET_PREFIX.length);
+    const preset = sections.flatMap((def) => def.presets ?? []).find((p) => p.id === id);
+    return preset ? preset.build(newId) : null;
+  }
+  const def = sections.find((d) => d.type === selection);
+  return def ? (def.defaults() as SectionContent) : null;
+}

package/src/lib/registry.ts

@@ -2,6 +2,7 @@ import type { ZodType, z } from "zod";
 import type { ComponentType, ReactNode } from "react";
 import type { Audience } from "../schemas/auth";
 import type { LinkValue } from "../schemas/link";
+import type { SectionContent } from "../schemas/sections";
 
 // --- Settings field types ---
 
@@ -106,6 +107,19 @@ export interface WrapperProps {
 
 // --- Section definition ---
 
+/**
+ * A ready-to-insert composite (e.g. a container of preconfigured child sections),
+ * surfaced in the Add-section menu. Contributed by the section definition that owns
+ * the composition, so it rides the section registry and disappears in a core-only
+ * build that never registers that section. `newId` mints unique ids for nested children.
+ */
+export interface SectionPreset {
+  id: string;
+  label: string;
+  icon?: ReactNode;
+  build(newId: () => string): SectionContent;
+}
+
 export interface SectionDefinition<T = unknown> {
   type: string;
   /** Grouping label. `"brand-guide"` marks opinionated sections separable from the
@@ -136,6 +150,14 @@ export interface SectionDefinition<T = unknown> {
    * into a trailing 'Other' tab.
    */
   settingsTabs?: { label: string; fields: string[] }[];
+  /** Composite blueprints for the Add-section menu (see SectionPreset). */
+  presets?: SectionPreset[];
+  /**
+   * Human/agent-facing prose describing when to use this section type and how to
+   * author it well. Surfaced by the get_section_schema tool as the JSON Schema
+   * top-level `description`. Presentation/metadata only — not validated.
+   */
+  authoringNote?: string;
 }
 
 // --- defineSection ---
@@ -162,6 +184,8 @@ type DefineSectionInput<S extends ZodType> = {
    * into a trailing 'Other' tab.
    */
   settingsTabs?: { label: string; fields: string[] }[];
+  presets?: SectionPreset[];
+  authoringNote?: string;
 };
 
 export function defineSection<S extends ZodType>(