@drawnagency/primitives 0.1.56 → 0.1.57

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

@@ -0,0 +1,18 @@
+import { defineSection } from "../../../lib/registry";
+import { z } from "zod";
+import { SquareDashed } from "lucide-react";
+import Spacer from "./Spacer";
+
+const schema = z.object({
+  type: z.literal("spacer"),
+  content: z.object({}).default({}),
+});
+
+export default defineSection({
+  type: "spacer",
+  label: "Spacer",
+  icon: <SquareDashed size={18} />,
+  schema,
+  component: () => <Spacer />,
+  defaults: () => ({ type: "spacer" as const, content: {} }),
+});

package/src/components/sections/all-sections.ts

@@ -2,13 +2,12 @@ import linkHeading from "./LinkHeading";
 import subHeading from "./SubHeading";
 import subSubHeading from "./SubSubHeading";
 import prose from "./Prose";
-import mediaGrid from "./MediaGrid";
-import splitContent from "./SplitContent";
+import media from "./Media";
 import button from "./Button";
 import colors from "./Colors";
-import doDontList from "./DoDontList";
-import doDontImageGrid from "./DoDontMediaGrid";
 import iconList from "./IconList";
+import container from "./Container";
+import spacer from "./Spacer";
 
 /**
  * The single ordered list of built-in section definitions.
@@ -18,6 +17,10 @@ import iconList from "./IconList";
  * array, so the two can no longer drift — previously they hand-maintained
  * parallel 11-entry lists, and a section added to one but not the other would
  * make the editor render a type that save rejects with a 400 (or vice versa).
+ *
+ * Retired: split_content, media_grid, do_dont_grid, do_dont — fully decomposable
+ * into container sections. The loader fallback in mergeSiteContent transforms any
+ * legacy-typed JSON to container before validation.
  */
 // Intentionally un-annotated: each section is SectionDefinition<its-own-shape>,
 // and a wider `SectionDefinition<unknown>[]` annotation isn't assignable from
@@ -28,11 +31,10 @@ export const allSectionDefs = [
   subHeading,
   subSubHeading,
   prose,
-  mediaGrid,
-  splitContent,
+  media,
   button,
   colors,
-  doDontList,
-  doDontImageGrid,
   iconList,
+  container,
+  spacer,
 ];

package/src/components/sections/register-schemas.ts

@@ -1,4 +1,4 @@
-import { registerSchema } from "../../lib/registry";
+import { registerSchema, registerRichText } from "../../lib/registry";
 import { allSectionDefs } from "./all-sections";
 
 // NOTE: this still imports the full (component-bearing) section modules via the
@@ -10,7 +10,10 @@ import { allSectionDefs } from "./all-sections";
 let _ensured = false;
 export function ensureSchemasRegistered(): number {
   if (!_ensured) {
-    allSectionDefs.forEach((def) => registerSchema(def.type, def.schema));
+    allSectionDefs.forEach((def) => {
+      registerSchema(def.type, def.schema);
+      if (def.richTextFields) registerRichText(def.type, def.richTextFields);
+    });
     _ensured = true;
   }
   return allSectionDefs.length;

package/src/components/shared/Tabs.tsx

@@ -0,0 +1,63 @@
+import { useState, type ReactNode } from "react";
+import { cn } from "../../lib/cn";
+
+export interface TabItem {
+  id: string;
+  label: string;
+  content: ReactNode;
+}
+
+interface TabsProps {
+  tabs: TabItem[];
+  /** Initial active tab when uncontrolled. Defaults to the first tab. */
+  defaultTabId?: string;
+  /** When provided, the component is controlled by the parent. */
+  activeTabId?: string;
+  onTabChange?: (id: string) => void;
+  /**
+   * When true, the tab-bar row uses -mx-6 to break out of the parent's px-6 padding
+   * (e.g. EditorModal's content wrapper) and re-pads with px-6 so buttons stay aligned.
+   * The tab panel inherits the parent's padding unchanged.
+   * Use only when the parent container has px-6; leave false for noPadding contexts.
+   */
+  fullBleedTabBar?: boolean;
+}
+
+export function Tabs({ tabs, defaultTabId, activeTabId, onTabChange, fullBleedTabBar }: TabsProps) {
+  const [uncontrolledId, setUncontrolledId] = useState(defaultTabId ?? tabs[0]?.id);
+  const isControlled = activeTabId !== undefined;
+  const activeId = isControlled ? activeTabId : uncontrolledId;
+  const activeTab = tabs.find((t) => t.id === activeId) ?? tabs[0];
+
+  function handleSelect(id: string) {
+    if (!isControlled) setUncontrolledId(id);
+    onTabChange?.(id);
+  }
+
+  return (
+    <div className="flex flex-1 flex-col overflow-hidden">
+      <div className={cn("border-b border-base-200", fullBleedTabBar && "-mx-6 px-6")}>
+        <div className="flex" role="tablist">
+          {tabs.map((tab) => (
+            <button
+              key={tab.id}
+              type="button"
+              role="tab"
+              aria-selected={activeTab?.id === tab.id}
+              onClick={() => handleSelect(tab.id)}
+              className={cn(
+                "cursor-pointer px-4 py-2 text-sm font-medium border-b-2 -mb-px",
+                activeTab?.id === tab.id
+                  ? "border-brand text-brand"
+                  : "border-transparent text-base-contrast-light hover:text-base-contrast",
+              )}
+            >
+              {tab.label}
+            </button>
+          ))}
+        </div>
+      </div>
+      <div role="tabpanel">{activeTab?.content}</div>
+    </div>
+  );
+}

package/src/components/shell/EditorShell.tsx

@@ -3,8 +3,9 @@ import { Fragment, useState, useCallback, useEffect, useRef, useMemo, type React
 import { monitorForElements } from "@atlaskit/pragmatic-drag-and-drop/element/adapter";
 import { combine } from "@atlaskit/pragmatic-drag-and-drop/combine";
 import { autoScrollWindowForElements } from "@atlaskit/pragmatic-drag-and-drop-auto-scroll/element";
+import { extractClosestEdge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
 import type { LoadedSection } from "../../lib/loader";
-import type { SectionContent } from "../../schemas/sections";
+import type { Section, SectionContent } from "../../schemas/sections";
 import type { SiteIndex, SiteConfig, Page } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 import type { MediaManifest } from "../../media/types";
@@ -12,6 +13,9 @@ import type { QueueItem } from "../../media/queue";
 import { SiteConfigSchema } from "../../schemas/site-config";
 import { ensureSanitizer } from "../../lib/sanitize";
 import { EditorProvider, useEditorContext } from "./EditorContext";
+import { makeBlockMoveDispatch } from "./blockMoveDispatch";
+import { ROOT_CONTAINER_ID, resolveDropIndex } from "../../lib/block-dnd";
+import type { BlockMove } from "../../lib/block-move";
 import { EditorModalProvider, useEditorModal } from "./EditorModalContext";
 import { EditorModal } from "./EditorModal";
 import { SiteSettingsModal } from "./SiteSettingsModal";
@@ -19,8 +23,10 @@ import { MediaLibraryModal } from "./MediaLibraryModal";
 import { MediaLibraryContext } from "./MediaLibraryContext";
 import { ProcessingIndicator } from "./ProcessingIndicator";
 import { SectionSkeleton } from "./SectionSkeleton";
+import { SectionTypePicker } from "./SectionTypePicker";
 import { ensureSectionsRegistered } from "../sections/register";
 import { getSection, getAllSections } from "../../lib/registry";
+import { childInsertableTypes, insertChildAt } from "../../lib/container-ops";
 
 ensureSectionsRegistered();
 import { BugReportFAB } from "./BugReportFAB";
@@ -145,6 +151,8 @@ export default function EditorShell({
   // doesn't enqueue a GitHub file deletion for a path that was never committed.
   const remoteSectionIdsRef = useRef<Set<string>>(new Set());
   const fontLinkRef = useRef<HTMLLinkElement | null>(null);
+  const sectionsRef = useRef<LoadedSection[]>([]);
+  useEffect(() => { sectionsRef.current = sections; }, [sections]);
   useEffect(() => { siteIndexRef.current = siteIndex; }, [siteIndex]);
   useEffect(() => { void ensureSanitizer(); }, []);
 
@@ -635,6 +643,24 @@ export default function EditorShell({
     [persistence, resolvedActivePage],
   );
 
+  const onBlockMove = useMemo(
+    () => makeBlockMoveDispatch({
+      getState: () => ({ sections: sectionsRef.current, index: siteIndexRef.current, rootPageId: resolvedActivePage?.id ?? homePage(siteIndexRef.current).id }),
+      setSections,
+      setSiteIndex,
+      persistence: { markSectionDirty: persistence.markSectionDirty, markIndexDirty: persistence.markIndexDirty, removeSection: persistence.removeSection },
+      isRemote: (id) => remoteSectionIdsRef.current.has(id),
+      scheduleDelete: (id) => setDeletedSections((prev) => new Set(prev).add(id)),
+      markLocalChanges: () => setLocalChangesExist(true),
+      newSectionContent: (id, secs) => {
+        const s = secs.find((x) => x.section.id === id)?.section;
+        const { id: _omit, ...content } = (s ?? { id }) as { id: string } & Record<string, unknown>;
+        return content as unknown as SectionContent;
+      },
+    }),
+    [persistence, resolvedActivePage],
+  );
+
   const handleMoveSection = useCallback((sectionId: string, destPageId: string, position: "top" | "bottom") => {
     const next = moveSectionReducer(siteIndexRef.current, sectionId, destPageId, position);
     setSiteIndex(next);
@@ -882,6 +908,7 @@ export default function EditorShell({
               onAddSection={onAddSection}
               onDeleteSection={setPendingDeleteSectionId}
               onReorderSections={onReorderSections}
+              onBlockMove={onBlockMove}
               onMoveSection={siteIndex.pages.length > 1 ? setMovingSectionId : undefined}
               onAccessChange={onAccessChange}
               onStatusChange={onStatusChange}
@@ -1140,6 +1167,7 @@ function EditorContent({
   onAddSection,
   onDeleteSection,
   onReorderSections,
+  onBlockMove,
   onMoveSection,
   onAccessChange,
   onStatusChange,
@@ -1156,6 +1184,7 @@ function EditorContent({
   onAddSection: (insertIndex: number, type: string) => void;
   onDeleteSection: (sectionId: string) => void;
   onReorderSections: (fromIndex: number, toIndex: number) => void;
+  onBlockMove: (move: BlockMove) => void;
   onMoveSection?: (sectionId: string) => void;
   onAccessChange: (sectionId: string, access: string[]) => void;
   onStatusChange: (sectionId: string, status: "draft" | "live" | "archived") => void;
@@ -1164,17 +1193,19 @@ function EditorContent({
   viewSections: LoadedSection[] | null;
 }) {
   const { isEditMode, viewBranch } = useEditorContext();
-  const { openModal } = useEditorModal();
+  const { openModal, closeModal } = useEditorModal();
   const [pendingInsertIndex, setPendingInsertIndex] = useState<number | null>(null);
   const dismissPendingInsert = useCallback(() => setPendingInsertIndex(null), []);
 
   const typeOptions = useMemo(
     () =>
-      getAllSections().map((def) => ({
-        type: def.type,
-        label: def.label,
-        icon: def.icon,
-      })),
+      getAllSections()
+        .filter((def) => def.type !== "spacer")
+        .map((def) => ({
+          type: def.type,
+          label: def.label,
+          icon: def.icon,
+        })),
     [],
   );
 
@@ -1192,19 +1223,42 @@ function EditorContent({
   useEffect(() => {
     return combine(
       monitorForElements({
-        onDragStart: ({ source }) => {
-          if (source.data.dragType === "section") {
-            setPendingInsertIndex(null);
+        canMonitor: ({ source }) => source.data.dragType === "block",
+        onDragStart: () => setPendingInsertIndex(null),
+        onDrop: ({ source, location }) => {
+          const target = location.current.dropTargets[0];
+          if (!target) return;
+          const s = source.data as { blockId: string; containerId: string; index: number };
+          const d = target.data as { dropContainerId: string; index: number; toColumn?: number };
+          if (d.toColumn != null) {
+            onBlockMove({
+              blockId: s.blockId,
+              fromContainerId: s.containerId,
+              fromIndex: s.index,
+              toContainerId: d.dropContainerId,
+              toIndex: 0,
+              toColumn: d.toColumn,
+            });
+            return;
           }
+          const edge = extractClosestEdge(target.data);
+          const toIndex = resolveDropIndex(d.index, edge);
+          onBlockMove({
+            blockId: s.blockId,
+            fromContainerId: s.containerId,
+            fromIndex: s.index,
+            toContainerId: d.dropContainerId,
+            toIndex,
+          });
         },
       }),
-      // Gradually scroll the window when a section drag nears the viewport
+      // Gradually scroll the window when a block drag nears the viewport
       // edge, so long reorders don't require repeated drag-and-release
       autoScrollWindowForElements({
-        canScroll: ({ source }) => source.data.dragType === "section",
+        canScroll: ({ source }) => source.data.dragType === "block",
       }),
     );
-  }, []);
+  }, [onBlockMove]);
 
   return (
     <div>
@@ -1245,6 +1299,8 @@ function EditorContent({
                   dirty={dirtySectionIds.has(section.id)}
                   index={index}
                   isLast={index === displaySections.length - 1}
+                  containerId={ROOT_CONTAINER_ID}
+                  isContainerBlock={section.type === "container"}
                   definition={definition}
                   mainStatus={mainIndex?.sections[section.id]?.status ?? null}
                   contentDiffersFromMain={changedSectionIds.has(section.id) || dirtySectionIds.has(section.id)}
@@ -1278,6 +1334,42 @@ function EditorContent({
                   onMoveSection={editingEnabled && onMoveSection ? () => onMoveSection(section.id) : undefined}
                   onRequestInsert={editingEnabled ? (i) => setPendingInsertIndex(i) : undefined}
                   onDelete={editingEnabled ? () => onDeleteSection(section.id) : undefined}
+                  onAddChild={
+                    editingEnabled && section.type === "container"
+                      ? () => {
+                          openModal(
+                            "Add block",
+                            <SectionTypePicker
+                              types={childInsertableTypes()}
+                              onClose={closeModal}
+                              onSelect={(type) => {
+                                const def = getSection(type);
+                                if (def) {
+                                  const id =
+                                    typeof crypto !== "undefined" && typeof crypto.randomUUID === "function"
+                                      ? crypto.randomUUID()
+                                      : `child-${Date.now()}`;
+                                  const child = { id, ...(def.defaults() as object) } as Section;
+                                  const containerSection: Section = {
+                                    id: section.id,
+                                    type: "container",
+                                    content: section.content as Record<string, unknown>,
+                                  };
+                                  const childCount =
+                                    (section.content as { children?: unknown[] }).children?.length ?? 0;
+                                  const next = insertChildAt(containerSection, child, childCount);
+                                  onSectionChange(section.id, {
+                                    ...section,
+                                    content: next.content,
+                                  } as SectionContent);
+                                }
+                                closeModal();
+                              }}
+                            />,
+                          );
+                        }
+                      : undefined
+                  }
                 >
                   <Component
                     content={section}

package/src/components/shell/SiteSettingsModal.tsx

@@ -1,10 +1,10 @@
 import { useState } from "react";
 import { EditorModal } from "./EditorModal";
 import { Button } from "../shared/Button";
+import { Tabs } from "../shared/Tabs";
 import { SiteSettingsViewerAccess } from "./SiteSettingsViewerAccess";
 import { SiteSettingsDisplay } from "./SiteSettingsDisplay";
 import { SiteSettingsUsers } from "./SiteSettingsUsers";
-import { cn } from "../../lib/cn";
 import type { SiteConfig } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 
@@ -25,17 +25,7 @@ interface Props {
   currentUser: { email: string; role: "owner" | "editor" } | null;
 }
 
-type TabId = "users" | "viewer-access" | "display";
-
 export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigChange, onAudiencesChange, capabilities, currentUser }: Props) {
-  const tabs: { id: TabId; label: string; show: boolean }[] = [
-    { id: "users", label: "Users", show: capabilities.userManagement && currentUser?.role === "owner" },
-    { id: "viewer-access", label: "Viewer Access", show: true },
-    { id: "display", label: "Display", show: true },
-  ];
-
-  const visibleTabs = tabs.filter((t) => t.show);
-  const [activeTab, setActiveTab] = useState<TabId>(visibleTabs[0]?.id ?? "display");
   const [signOutError, setSignOutError] = useState<string | null>(null);
 
   async function handleSignOut() {
@@ -58,49 +48,49 @@ export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigCha
       ? (currentUser.role === "owner" ? "Owner" : "Editor")
       : null;
 
+  const allTabs = [
+    {
+      id: "users",
+      label: "Users",
+      show: capabilities.userManagement && currentUser?.role === "owner",
+      content: (
+        <div data-testid="site-settings-tab-panel" className="flex flex-1 flex-col overflow-y-auto px-6 py-4">
+          <SiteSettingsUsers currentUser={currentUser} />
+        </div>
+      ),
+    },
+    {
+      id: "viewer-access",
+      label: "Viewer Access",
+      show: true,
+      content: (
+        <div data-testid="site-settings-tab-panel" className="flex flex-1 flex-col overflow-y-auto px-6 py-4">
+          <SiteSettingsViewerAccess
+            audienceManagement={capabilities.audienceManagement}
+            passwordToggle={capabilities.passwordToggle}
+            onAudiencesChange={onAudiencesChange}
+          />
+        </div>
+      ),
+    },
+    {
+      id: "display",
+      label: "Display",
+      show: true,
+      content: (
+        <div data-testid="site-settings-tab-panel" className="flex flex-1 flex-col overflow-y-auto px-6 py-4">
+          <SiteSettingsDisplay siteConfig={siteConfig} onChange={onSiteConfigChange} />
+        </div>
+      ),
+    },
+  ];
+
+  const tabItems = allTabs.filter((t) => t.show).map(({ id, label, content }) => ({ id, label, content }));
+
   return (
     <EditorModal isOpen={isOpen} onClose={onClose} title="Site Settings" size="settings" noPadding>
       <div className="flex flex-1 flex-col overflow-hidden">
-        <div className="border-b border-base-200">
-          <div className="flex px-6" role="tablist">
-            {visibleTabs.map((tab) => (
-              <button
-                key={tab.id}
-                role="tab"
-                aria-selected={activeTab === tab.id}
-                onClick={() => setActiveTab(tab.id)}
-                className={cn(
-                  "cursor-pointer px-4 py-2 text-sm font-medium border-b-2 -mb-px",
-                  activeTab === tab.id
-                    ? "border-brand text-brand"
-                    : "border-transparent text-base-contrast-light hover:text-base-contrast",
-                )}
-              >
-                {tab.label}
-              </button>
-            ))}
-          </div>
-        </div>
-
-        <div
-          data-testid="site-settings-tab-panel"
-          className="flex flex-1 flex-col overflow-y-auto px-6 py-4"
-        >
-          {activeTab === "users" && <SiteSettingsUsers currentUser={currentUser} />}
-          {activeTab === "viewer-access" && (
-            <SiteSettingsViewerAccess
-                audienceManagement={capabilities.audienceManagement}
-                passwordToggle={capabilities.passwordToggle}
-                onAudiencesChange={onAudiencesChange}
-              />
-          )}
-          {activeTab === "display" && (
-            <SiteSettingsDisplay
-              siteConfig={siteConfig}
-              onChange={onSiteConfigChange}
-            />
-          )}
-        </div>
+        <Tabs tabs={tabItems} />
 
         {currentUser && (
           <div className="flex items-center justify-between gap-3 border-t border-base-200 px-6 py-3">

package/src/components/shell/blockMoveDispatch.ts

@@ -0,0 +1,40 @@
+import { applyBlockMove, type BlockMove, type BlockMoveState } from "../../lib/block-move";
+import type { LoadedSection } from "../../lib/loader";
+import type { SiteIndex } from "../../schemas/site-config";
+import type { SectionContent } from "../../schemas/sections";
+
+export interface BlockMoveDispatchDeps {
+  getState: () => BlockMoveState;
+  setSections: (updater: (prev: LoadedSection[]) => LoadedSection[]) => void;
+  setSiteIndex: (updater: (prev: SiteIndex) => SiteIndex) => void;
+  persistence: {
+    markSectionDirty: (id: string, content: SectionContent) => void;
+    markIndexDirty: () => void;
+    removeSection: (id: string) => void;
+  };
+  isRemote: (id: string) => boolean;
+  scheduleDelete: (id: string) => void;
+  markLocalChanges: () => void;
+  /** Latest content for a section id, for markSectionDirty after the move. */
+  newSectionContent: (id: string, sections: LoadedSection[]) => SectionContent;
+}
+
+export function makeBlockMoveDispatch(deps: BlockMoveDispatchDeps) {
+  return function onBlockMove(move: BlockMove) {
+    const result = applyBlockMove(deps.getState(), move);
+    if (!result.changed) return;
+
+    deps.setSections(() => result.sections);
+    deps.setSiteIndex(() => result.index);
+
+    for (const id of result.effects.deleteSectionIds) {
+      if (deps.isRemote(id)) deps.scheduleDelete(id);
+      deps.persistence.removeSection(id);
+    }
+    for (const id of result.effects.markDirtySectionIds) {
+      deps.persistence.markSectionDirty(id, deps.newSectionContent(id, result.sections));
+    }
+    if (result.effects.indexDirty) deps.persistence.markIndexDirty();
+    deps.markLocalChanges();
+  };
+}

package/src/hooks/useBlockDnd.ts

@@ -0,0 +1,144 @@
+import { useEffect, useRef, useState } from "react";
+import type { Edge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
+import { buildBlockDragData, buildBlockDropData, isBlockDragData, canDropBlock } from "../lib/block-dnd";
+
+type AllowedEdges = Edge[];
+
+export interface UseBlockDndArgs {
+  blockId: string;
+  containerId: string;
+  index: number;
+  isContainer: boolean;
+  /** ["left","right"] inside a row container, ["top","bottom"] at root */
+  allowedEdges: AllowedEdges;
+  enabled: boolean;
+}
+
+/**
+ * Wires a block as a unified drag source + drop target. Manages only this block's
+ * local hover edge + dragging flag — the actual move dispatch is centralized in the
+ * EditorContent monitor (a later task), so nested targets never double-fire. The edge
+ * indicator is shown only when this element is the innermost drop target.
+ *
+ * Callers must pass a stable `allowedEdges` array (module-level constant or memoized)
+ * to avoid re-subscribing on every render.
+ */
+export function useBlockDnd({ blockId, containerId, index, isContainer, allowedEdges, enabled }: UseBlockDndArgs) {
+  const dragRef = useRef<HTMLDivElement>(null);
+  const handleRef = useRef<HTMLButtonElement>(null);
+  const [closestEdge, setClosestEdge] = useState<Edge | null>(null);
+  const [isDragging, setIsDragging] = useState(false);
+
+  useEffect(() => {
+    const element = dragRef.current;
+    const handle = handleRef.current;
+    if (!element || !enabled) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    Promise.all([
+      import("@atlaskit/pragmatic-drag-and-drop/element/adapter"),
+      import("@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge"),
+    ]).then(([{ draggable, dropTargetForElements }, { attachClosestEdge, extractClosestEdge }]) => {
+      if (cancelled) return;
+
+      const cleanupDraggable = draggable({
+        element,
+        dragHandle: handle ?? undefined,
+        getInitialData: () => buildBlockDragData({ blockId, containerId, index, isContainer }),
+        onGenerateDragPreview: () => {
+          element.style.opacity = "0.4";
+          requestAnimationFrame(() => { element.style.opacity = ""; });
+        },
+        onDragStart: () => setIsDragging(true),
+        onDrop: () => setIsDragging(false),
+      });
+
+      const cleanupDrop = dropTargetForElements({
+        element,
+        canDrop: ({ source }) => isBlockDragData(source.data) && canDropBlock(source.data, containerId),
+        getData: ({ input, element: el }) =>
+          attachClosestEdge(buildBlockDropData({ dropContainerId: containerId, index }), {
+            input, element: el, allowedEdges,
+          }),
+        onDrag: ({ self, source, location }) => {
+          const innermost = location.current.dropTargets[0]?.element === self.element;
+          if (!innermost || !isBlockDragData(source.data) || source.data.blockId === blockId) {
+            setClosestEdge(null);
+            return;
+          }
+          setClosestEdge(extractClosestEdge(self.data));
+        },
+        onDragLeave: () => setClosestEdge(null),
+        onDrop: () => setClosestEdge(null),
+      });
+
+      cleanup = () => { cleanupDraggable(); cleanupDrop(); };
+    });
+
+    return () => { cancelled = true; cleanup?.(); };
+  }, [blockId, containerId, index, isContainer, enabled, allowedEdges]);
+
+  return { dragRef, handleRef, closestEdge, isDragging };
+}
+
+export interface UseBlockDropZoneArgs {
+  containerId: string;
+  index: number;
+  /** When set, the zone is a column-targeted drop (ghost/spacer): place at this 1-based column. */
+  toColumn?: number;
+  allowedEdges: AllowedEdges;
+  enabled: boolean;
+}
+
+/**
+ * A drop-target-ONLY zone (not draggable) — used for an empty container's first-drop
+ * area, where there are no child cells to act as targets. It advertises
+ * `{ dropContainerId, index }` and shows an edge indicator only when it is the innermost
+ * drop target. The actual move dispatch is centralized in the EditorContent monitor.
+ *
+ * Callers must pass a stable `allowedEdges` array (module-level constant or memoized).
+ */
+export function useBlockDropZone({ containerId, index, toColumn, allowedEdges, enabled }: UseBlockDropZoneArgs) {
+  const dropRef = useRef<HTMLDivElement>(null);
+  const [closestEdge, setClosestEdge] = useState<Edge | null>(null);
+
+  useEffect(() => {
+    const element = dropRef.current;
+    if (!element || !enabled) return;
+
+    let cleanup: (() => void) | undefined;
+    let cancelled = false;
+
+    Promise.all([
+      import("@atlaskit/pragmatic-drag-and-drop/element/adapter"),
+      import("@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge"),
+    ]).then(([{ dropTargetForElements }, { attachClosestEdge, extractClosestEdge }]) => {
+      if (cancelled) return;
+
+      cleanup = dropTargetForElements({
+        element,
+        canDrop: ({ source }) => isBlockDragData(source.data) && canDropBlock(source.data, containerId),
+        getData: ({ input, element: el }) =>
+          attachClosestEdge(buildBlockDropData({ dropContainerId: containerId, index, toColumn }), {
+            input, element: el, allowedEdges,
+          }),
+        onDrag: ({ self, source, location }) => {
+          const innermost = location.current.dropTargets[0]?.element === self.element;
+          if (!innermost || !isBlockDragData(source.data)) {
+            setClosestEdge(null);
+            return;
+          }
+          setClosestEdge(extractClosestEdge(self.data));
+        },
+        onDragLeave: () => setClosestEdge(null),
+        onDrop: () => setClosestEdge(null),
+      });
+    });
+
+    return () => { cancelled = true; cleanup?.(); };
+  }, [containerId, index, toColumn, enabled, allowedEdges]);
+
+  return { dropRef, closestEdge };
+}