@portaki/module-sections 1.3.0 → 1.4.0

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@portaki/module-sections",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Portaki module — editorial sections (TipTap)",
   "license": "AGPL-3.0",
   "type": "module",
   "main": "./src/index.tsx",
   "dependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@portaki/sdk": "^3.0.0",
+    "lucide-react": "^1.14.0",
     "@tiptap/core": "^3.0.0",
     "@tiptap/html": "^3.0.0",
     "@tiptap/starter-kit": "^3.0.0",

package/portaki.catalog.json

@@ -9,7 +9,7 @@
     "fr": "Blocs de contenu riches (TipTap) pour le carnet d’accueil invité.",
     "en": "Rich content blocks (TipTap) for the guest welcome book."
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "releaseNotesUrl": "https://github.com/PortakiApp/portaki-modules/releases",
   "changelog": [
     {
@@ -122,6 +122,6 @@
   },
   "artifacts": {
     "wasmUrl": "oci://ghcr.io/portakiapp/portaki-module-sections",
-    "guestEsmUrl": "https://esm.sh/@portaki/module-sections@1.3.0"
+    "guestEsmUrl": "https://esm.sh/@portaki/module-sections@1.4.0"
   }
 }

package/portaki.module.json

@@ -9,7 +9,7 @@
     "fr": "Blocs de contenu riches (TipTap) pour le carnet d’accueil invité.",
     "en": "Rich content blocks (TipTap) for the guest welcome book."
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "releaseNotesUrl": "https://github.com/PortakiApp/portaki-modules/releases",
   "changelog": [
     {
@@ -122,6 +122,6 @@
   },
   "artifacts": {
     "wasmUrl": "oci://ghcr.io/portakiapp/portaki-module-sections",
-    "guestEsmUrl": "https://esm.sh/@portaki/module-sections@1.3.0"
+    "guestEsmUrl": "https://esm.sh/@portaki/module-sections@1.4.0"
   }
 }

package/src/host/SectionCreateModal.tsx

@@ -0,0 +1,159 @@
+'use client'
+
+import type { HostModuleContext } from '@portaki/sdk'
+import { useEffect, useState } from 'react'
+
+import type {
+  SectionContentPresetId,
+  SectionCreateModalDesign,
+  SectionTemplateDesign,
+} from './sections-host.types'
+
+export type SectionCreatePayload = {
+  titleFr: string
+  titleEn: string
+  contentPreset: SectionContentPresetId
+}
+
+type Props = {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  design: SectionCreateModalDesign
+  onCreate: (payload: SectionCreatePayload) => Promise<void>
+  creating?: boolean
+  shell: HostModuleContext['shell']
+}
+
+export function SectionCreateModal({
+  open,
+  onOpenChange,
+  design,
+  onCreate,
+  creating = false,
+  shell,
+}: Props) {
+  const {
+    Dialog,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    Button,
+    Input,
+    cn,
+  } = shell
+
+  const defaultTemplate =
+    design.templates.find((t) => t.id === design.defaultTemplateId) ?? design.templates[0]
+
+  const [selectedId, setSelectedId] = useState(defaultTemplate?.id ?? '')
+  const [titleFr, setTitleFr] = useState(defaultTemplate?.titleFr ?? '')
+
+  const selected = design.templates.find((t) => t.id === selectedId) ?? defaultTemplate
+
+  useEffect(() => {
+    if (!open || !defaultTemplate) {
+      return
+    }
+    setSelectedId(defaultTemplate.id)
+    setTitleFr(defaultTemplate.titleFr)
+  }, [open, defaultTemplate])
+
+  function selectTemplate(template: SectionTemplateDesign) {
+    setSelectedId(template.id)
+    setTitleFr(template.titleFr)
+  }
+
+  async function handleSubmit() {
+    if (!selected || !titleFr.trim()) {
+      return
+    }
+    await onCreate({
+      titleFr: titleFr.trim(),
+      titleEn: selected.titleEn,
+      contentPreset: selected.contentPreset,
+    })
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="flex max-h-[min(92vh,calc(100%-80px))] max-w-[min(96vw,920px)] flex-col gap-0 overflow-hidden p-0">
+        <DialogHeader className="shrink-0 px-[26px] pb-4 pt-6">
+          <DialogTitle className="font-heading text-[22px] font-semibold tracking-tight">
+            {design.titleFr}
+          </DialogTitle>
+          <DialogDescription className="text-[13px] leading-relaxed text-[var(--text-muted)]">
+            {design.subtitleFr}
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="min-h-0 flex-1 overflow-y-auto px-[26px] pb-4">
+          <div className="grid grid-cols-1 gap-2.5 sm:grid-cols-2 lg:grid-cols-3">
+            {design.templates.map((template) => {
+              const active = template.id === selectedId
+              return (
+                <button
+                  key={template.id}
+                  type="button"
+                  onClick={() => selectTemplate(template)}
+                  className={cn(
+                    'rounded-xl border px-3 py-3 text-left transition-colors',
+                    active
+                      ? 'border-[var(--amber)] bg-[var(--color-amber-soft)] shadow-[inset_0_0_0_1px_rgba(245,158,11,0.35)]'
+                      : 'border-[var(--border)] bg-white hover:border-[var(--border-md)] hover:bg-[var(--bg-muted)]/40',
+                  )}
+                >
+                  <span className="text-[22px] leading-none" aria-hidden>
+                    {template.icon}
+                  </span>
+                  <p className="mt-2 font-heading text-[14px] font-semibold leading-snug text-[var(--text)]">
+                    {template.titleFr}
+                  </p>
+                  <p className="mt-1 text-[12px] leading-snug text-[var(--text-muted)]">
+                    {template.descriptionFr}
+                  </p>
+                </button>
+              )
+            })}
+          </div>
+
+          <div className="mt-5">
+            <label className="mb-1.5 block text-[13px] font-medium text-[var(--text)]">
+              {design.titleFieldLabelFr}
+            </label>
+            <Input
+              value={titleFr}
+              onChange={(e) => setTitleFr(e.target.value)}
+              placeholder={selected?.titleFr}
+              className="h-11"
+            />
+            <p className="mt-1.5 text-[12px] text-[var(--text-muted)]">{design.titleFieldHintFr}</p>
+          </div>
+
+          <p className="mt-4 text-[12px] text-[var(--text-muted)]">{design.footerHintFr}</p>
+        </div>
+
+        <DialogFooter className="shrink-0 flex-row items-center justify-end gap-2 border-t border-[var(--border)] bg-[var(--bg-surface)] px-[26px] py-4">
+          <Button
+            type="button"
+            variant="ghost"
+            className="text-[var(--text-muted)]"
+            disabled={creating}
+            onClick={() => onOpenChange(false)}
+          >
+            {design.cancelLabelFr}
+          </Button>
+          <Button
+            type="button"
+            className="bg-[var(--amber)] font-semibold text-[var(--text)] hover:bg-[var(--amber-solid-hover)]"
+            disabled={creating || !titleFr.trim()}
+            onClick={() => void handleSubmit()}
+          >
+            {creating ? 'Création…' : design.submitLabelFr}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/host/SectionsHostWorkspace.tsx

@@ -0,0 +1,501 @@
+'use client'
+
+import type { HostModuleContext } from '@portaki/sdk'
+import {
+  DndContext,
+  closestCenter,
+  KeyboardSensor,
+  PointerSensor,
+  useSensor,
+  useSensors,
+  type DragEndEvent,
+} from '@dnd-kit/core'
+import {
+  SortableContext,
+  arrayMove,
+  sortableKeyboardCoordinates,
+  useSortable,
+  verticalListSortingStrategy,
+} from '@dnd-kit/sortable'
+import { CSS } from '@dnd-kit/utilities'
+import { FileText, GripVertical, Plus, Trash2 } from 'lucide-react'
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+
+import { SectionCreateModal, type SectionCreatePayload } from './SectionCreateModal'
+import type { SectionsEditorDesign } from './sections-host.types'
+
+type SectionRow = {
+  id: string;
+  sortOrder: number;
+  titleFr: string;
+  titleEn: string;
+  contentFr: unknown;
+  contentEn: unknown;
+};
+
+type LangTab = "fr" | "en";
+
+function unwrapJsonbField(
+  raw: unknown,
+  parseTipTapDoc: HostModuleContext['shell']['parseTipTapDoc'],
+): unknown {
+  if (raw == null) {
+    return null;
+  }
+  if (typeof raw === "string") {
+    return parseTipTapDoc(raw);
+  }
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    const record = raw as Record<string, unknown>;
+    if (record.type === "jsonb" && record.value != null) {
+      return unwrapJsonbField(record.value, parseTipTapDoc);
+    }
+    if (record.type === "doc") {
+      return record;
+    }
+  }
+  return raw;
+}
+
+function normalizeSectionRow(
+  row: Record<string, unknown>,
+  parseTipTapDoc: HostModuleContext['shell']['parseTipTapDoc'],
+): SectionRow {
+  return {
+    id: String(row.id ?? ""),
+    sortOrder: Number(row.sortOrder ?? row.sort_order ?? 0),
+    titleFr: String(row.titleFr ?? row.title_fr ?? ""),
+    titleEn: String(row.titleEn ?? row.title_en ?? ""),
+    contentFr: unwrapJsonbField(row.contentFr ?? row.content_fr, parseTipTapDoc),
+    contentEn: unwrapJsonbField(row.contentEn ?? row.content_en, parseTipTapDoc),
+  };
+}
+
+function tipTapValue(
+  raw: unknown,
+  shell: HostModuleContext['shell'],
+): string {
+  const doc = unwrapJsonbField(raw, shell.parseTipTapDoc);
+  if (doc && typeof doc === "object") {
+    return shell.serializeTipTapDoc(doc as Record<string, unknown>);
+  }
+  return shell.serializeTipTapDoc(shell.parseTipTapDoc(null));
+}
+
+function SortableSectionItem({
+  section,
+  selected,
+  onSelect,
+  cn,
+}: {
+  section: SectionRow
+  selected: boolean
+  onSelect: () => void
+  cn: HostModuleContext['shell']['cn']
+}) {
+  const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({
+    id: section.id,
+  });
+  const style = {
+    transform: CSS.Transform.toString(transform),
+    transition,
+  };
+
+  return (
+    <li ref={setNodeRef} style={style} className={cn(isDragging && "z-10 opacity-90")}>
+      <div
+        className={cn(
+          "flex items-center gap-1 rounded-lg px-1 py-0.5",
+          selected ? "bg-[var(--amber)]/12" : "hover:bg-black/[0.03]",
+        )}
+      >
+        <button
+          type="button"
+          className="touch-none rounded p-1 text-[var(--text-muted)] hover:text-[var(--text)]"
+          aria-label="Réordonner"
+          {...attributes}
+          {...listeners}
+        >
+          <GripVertical className="size-4" aria-hidden />
+        </button>
+        <button
+          type="button"
+          onClick={onSelect}
+          className={cn(
+            "min-w-0 flex-1 rounded-md px-2 py-2 text-left text-[13px] transition-colors",
+            selected ? "font-medium text-[var(--text)]" : "text-[var(--text-muted)] hover:text-[var(--text)]",
+          )}
+        >
+          {section.titleFr || "Sans titre"}
+        </button>
+      </div>
+    </li>
+  );
+}
+
+export function SectionsHostWorkspace({ ctx }: { ctx: HostModuleContext }) {
+  const design = ctx.design as SectionsEditorDesign
+  const { propertyId, gateway, shell } = ctx
+  const toasts = design.toasts
+  const {
+    NotionLikeEditor,
+    HostEmptyPlaceholder,
+    HostUnderlineTabs,
+    Button,
+    Input,
+    cn,
+    toast,
+    parseTipTapDoc,
+    serializeTipTapDoc,
+  } = shell
+  const gatewayOps = design.gateway
+
+  const [sections, setSections] = useState<SectionRow[]>([]);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [lang, setLang] = useState<LangTab>("fr");
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [creating, setCreating] = useState(false);
+  const [createModalOpen, setCreateModalOpen] = useState(false);
+  const [lastSavedAt, setLastSavedAt] = useState<Date | null>(null);
+
+  const sensors = useSensors(
+    useSensor(PointerSensor, { activationConstraint: { distance: 6 } }),
+    useSensor(KeyboardSensor, { coordinateGetter: sortableKeyboardCoordinates }),
+  );
+
+  const selected = useMemo(
+    () => sections.find((s) => s.id === selectedId) ?? null,
+    [sections, selectedId],
+  );
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      const data = await gateway.query<SectionRow[]>(gatewayOps.listQuery)
+      const list = data.map((row) => normalizeSectionRow(row as Record<string, unknown>, parseTipTapDoc));
+      setSections(list);
+      setSelectedId((prev) => {
+        if (prev && list.some((s) => s.id === prev)) {
+          return prev;
+        }
+        return list[0]?.id ?? null;
+      });
+    } catch {
+      toast.error(toasts.loadError)
+    } finally {
+      setLoading(false);
+    }
+  }, [propertyId, gateway, gatewayOps.listQuery, toast])
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const saveSelected = useCallback(
+    async (draft: SectionRow) => {
+      setSaving(true);
+      try {
+        await gateway.command(gatewayOps.saveCommand, {
+          id: draft.id,
+          titleFr: draft.titleFr,
+          titleEn: draft.titleEn || draft.titleFr,
+          contentFr: draft.contentFr,
+          contentEn: draft.contentEn,
+          sortOrder: draft.sortOrder,
+        });
+        setLastSavedAt(new Date());
+        await load();
+      } catch {
+        toast.error(toasts.saveError)
+      } finally {
+        setSaving(false);
+      }
+    },
+    [gateway, gatewayOps.saveCommand, load, toast],
+  );
+
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const scheduleSave = useCallback(
+    (draft: SectionRow) => {
+      if (debounceRef.current) {
+        clearTimeout(debounceRef.current);
+      }
+      debounceRef.current = setTimeout(() => {
+        void saveSelected(draft);
+      }, 1200);
+    },
+    [saveSelected],
+  );
+
+  const updateDraft = useCallback(
+    (patch: Partial<SectionRow>) => {
+      if (!selected) {
+        return;
+      }
+      const next = { ...selected, ...patch };
+      setSections((prev) => prev.map((s) => (s.id === next.id ? next : s)));
+      scheduleSave(next);
+    },
+    [selected, scheduleSave],
+  );
+
+  const persistOrder = useCallback(
+    async (ordered: SectionRow[]) => {
+      try {
+        await gateway.command(gatewayOps.reorderCommand, {
+          orderedIds: ordered.map((s) => s.id),
+        });
+      } catch {
+        toast.error(toasts.reorderError)
+        await load();
+      }
+    },
+    [gateway, gatewayOps.reorderCommand, load, toast]
+  );
+
+  const onDragEnd = useCallback(
+    (event: DragEndEvent) => {
+      const { active, over } = event;
+      if (!over || active.id === over.id) {
+        return;
+      }
+      setSections((items) => {
+        const oldIndex = items.findIndex((s) => s.id === active.id);
+        const newIndex = items.findIndex((s) => s.id === over.id);
+        const moved = arrayMove(items, oldIndex, newIndex).map((s, index) => ({
+          ...s,
+          sortOrder: index,
+        }));
+        void persistOrder(moved);
+        return moved;
+      });
+    },
+    [persistOrder],
+  );
+
+  const createSection = useCallback(
+    async (payload: SectionCreatePayload) => {
+      setCreating(true);
+      const sortOrder = sections.length;
+      const id = crypto.randomUUID();
+      const buildPreset = shell.buildSectionTipTapPreset
+      if (buildPreset == null) {
+        throw new Error('host_shell_missing_buildSectionTipTapPreset')
+      }
+      const { contentFr, contentEn } = buildPreset(payload.contentPreset)
+      try {
+        await gateway.command(gatewayOps.saveCommand, {
+          id,
+          titleFr: payload.titleFr,
+          titleEn: payload.titleEn,
+          contentFr,
+          contentEn,
+          sortOrder,
+        });
+        setCreateModalOpen(false);
+        await load();
+        setSelectedId(id);
+        toast.success(toasts.createSuccess)
+      } catch {
+        toast.error(toasts.createError)
+      } finally {
+        setCreating(false);
+      }
+    },
+    [gateway, gatewayOps.saveCommand, sections.length, load, toast]
+  );
+
+  const deleteSelected = useCallback(async () => {
+    if (!selected) {
+      return;
+    }
+    try {
+      await gateway.command(gatewayOps.deleteCommand, {
+        id: selected.id,
+      });
+      toast.success(toasts.deleteSuccess)
+      await load();
+    } catch {
+      toast.error(toasts.deleteError)
+    }
+  }, [gateway, gatewayOps.deleteCommand, selected, load, toast])
+
+  if (loading) {
+    return <p className="text-sm text-[var(--text-muted)]">Chargement des sections…</p>;
+  }
+
+  if (sections.length === 0) {
+    return (
+      <>
+        <HostEmptyPlaceholder
+          icon={FileText}
+          title={design.emptyState.titleFr}
+          description={design.emptyState.descriptionFr}
+          primaryAction={{
+            label: design.emptyState.primaryActionLabelFr,
+            onClick: () => setCreateModalOpen(true),
+          }}
+        />
+        <SectionCreateModal
+          open={createModalOpen}
+          onOpenChange={setCreateModalOpen}
+          design={design.createModal}
+          onCreate={createSection}
+          creating={creating}
+          shell={shell}
+        />
+      </>
+    )
+  }
+
+  const editorValue =
+    selected == null
+      ? serializeTipTapDoc(parseTipTapDoc(null))
+      : lang === "fr"
+        ? tipTapValue(selected.contentFr, shell)
+        : tipTapValue(selected.contentEn, shell);
+
+  return (
+    <div className="flex min-h-[min(70vh,720px)] flex-col gap-4 lg:flex-row">
+      <aside className="w-full shrink-0 rounded-xl border border-[var(--border)] bg-white lg:w-72">
+        <div className="flex items-center justify-between border-b border-[var(--border)] px-3 py-2.5">
+          <span className="text-[13px] font-medium text-[var(--text)]">Sections</span>
+          <Button
+            type="button"
+            variant="secondary"
+            className="min-h-8 px-3 text-xs"
+            onClick={() => setCreateModalOpen(true)}
+          >
+            <Plus className="size-4" aria-hidden />
+            Nouvelle
+          </Button>
+        </div>
+        <DndContext sensors={sensors} collisionDetection={closestCenter} onDragEnd={onDragEnd}>
+          <SortableContext items={sections.map((s) => s.id)} strategy={verticalListSortingStrategy}>
+            <ul className="max-h-[min(60vh,560px)] overflow-y-auto p-2">
+              {sections.length === 0 ? (
+                <li className="px-2 py-8 text-center">
+                  <p className="text-[13px] text-[var(--text-muted)]">Aucune section pour l&apos;instant.</p>
+                  <Button
+                    type="button"
+                    variant="secondary"
+                    className="mt-3 min-h-9 px-4 text-xs"
+                    onClick={() => setCreateModalOpen(true)}
+                  >
+                    <Plus className="size-4" aria-hidden />
+                    Nouvelle section
+                  </Button>
+                </li>
+              ) : (
+                sections.map((s) => (
+                  <SortableSectionItem
+                    key={s.id}
+                    section={s}
+                    selected={selectedId === s.id}
+                    onSelect={() => setSelectedId(s.id)}
+                    cn={cn}
+                  />
+                ))
+              )}
+            </ul>
+          </SortableContext>
+        </DndContext>
+      </aside>
+
+      <div className="min-w-0 flex-1 rounded-xl border border-[var(--border)] bg-white">
+        {selected ? (
+          <>
+            <div className="flex flex-col gap-3 border-b border-[var(--border)] px-4 py-3">
+              <div className="flex flex-wrap items-center gap-2">
+                <Input
+                  value={selected.titleFr}
+                  onChange={(e) => updateDraft({ titleFr: e.target.value })}
+                  placeholder="Titre (FR)"
+                  className="max-w-xs"
+                />
+                <Input
+                  value={selected.titleEn}
+                  onChange={(e) => updateDraft({ titleEn: e.target.value })}
+                  placeholder="Title (EN)"
+                  className="max-w-xs"
+                />
+                <div className="ml-auto flex items-center gap-2">
+                  <span className="text-[11px] text-[var(--text-muted)]">
+                    {saving
+                      ? "Enregistrement…"
+                      : lastSavedAt
+                        ? `Auto-sauvegardé — ${formatRelative(lastSavedAt)}`
+                        : ""}
+                  </span>
+                  <Button
+                    type="button"
+                    variant="ghost"
+                    className="min-h-8 px-3 text-xs text-destructive"
+                    onClick={() => void deleteSelected()}
+                  >
+                    <Trash2 className="size-4" aria-hidden />
+                    Supprimer
+                  </Button>
+                </div>
+              </div>
+              <HostUnderlineTabs
+                options={[
+                  { value: 'fr', label: 'Contenu FR' },
+                  { value: 'en', label: 'Content EN' },
+                ]}
+                value={lang}
+                onChange={(value) => setLang(value as LangTab)}
+                ariaLabel="Langue du contenu"
+              />
+            </div>
+            <div className="p-4">
+              <NotionLikeEditor
+                key={`${selected.id}-${lang}`}
+                value={editorValue}
+                onChange={(json) => {
+                  try {
+                    const node = JSON.parse(json) as unknown;
+                    if (lang === "fr") {
+                      updateDraft({ contentFr: node });
+                    } else {
+                      updateDraft({ contentEn: node });
+                    }
+                  } catch {
+                    /* ignore */
+                  }
+                }}
+              />
+            </div>
+          </>
+        ) : (
+          <div className="flex min-h-[320px] items-center justify-center p-8 text-[13px] text-[var(--text-muted)]">
+            Sélectionnez ou créez une section.
+          </div>
+        )}
+      </div>
+
+      <SectionCreateModal
+        open={createModalOpen}
+        onOpenChange={setCreateModalOpen}
+        design={design.createModal}
+        onCreate={createSection}
+        creating={creating}
+        shell={shell}
+      />
+    </div>
+  )
+}
+
+function formatRelative(d: Date): string {
+  const sec = Math.round((Date.now() - d.getTime()) / 1000);
+  if (sec < 8) {
+    return "à l’instant";
+  }
+  if (sec < 60) {
+    return `il y a ${sec} s`;
+  }
+  const min = Math.round(sec / 60);
+  return `il y a ${min} min`;
+}

package/src/host/sections-host.types.ts

@@ -0,0 +1,62 @@
+export const SECTION_CONTENT_PRESET_IDS = [
+  'welcome',
+  'beaches',
+  'restaurants',
+  'transport',
+  'emergencies',
+  'empty',
+] as const
+
+export type SectionContentPresetId = (typeof SECTION_CONTENT_PRESET_IDS)[number]
+
+export type SectionTemplateId = SectionContentPresetId
+
+export type SectionsEditorEmptyStateDesign = {
+  titleFr: string
+  descriptionFr: string
+  primaryActionLabelFr: string
+}
+
+export type SectionCreateModalDesign = {
+  titleFr: string
+  subtitleFr: string
+  titleFieldLabelFr: string
+  titleFieldHintFr: string
+  footerHintFr: string
+  cancelLabelFr: string
+  submitLabelFr: string
+  defaultTemplateId: SectionTemplateId
+  templates: readonly SectionTemplateDesign[]
+}
+
+export type SectionTemplateDesign = {
+  id: SectionTemplateId
+  icon: string
+  titleFr: string
+  titleEn: string
+  descriptionFr: string
+  contentPreset: SectionContentPresetId
+}
+
+export type SectionsEditorDesign = {
+  id: 'sections-editor-v1'
+  moduleId: 'sections'
+  layout: 'sections-split-panel'
+  gateway: {
+    listQuery: 'sections.list'
+    saveCommand: 'sections.section.save'
+    deleteCommand: 'sections.section.delete'
+    reorderCommand: 'sections.reorder'
+  }
+  createModal: SectionCreateModalDesign
+  emptyState: SectionsEditorEmptyStateDesign
+  toasts: {
+    loadError: string
+    saveError: string
+    reorderError: string
+    createSuccess: string
+    createError: string
+    deleteSuccess: string
+    deleteError: string
+  }
+}

package/src/module.test.tsx

@@ -1,17 +1,32 @@
 import { describe, expect, it } from 'vitest'
 import { waitFor } from '@testing-library/react'
-import { assertGuestSurface, renderGuestModule } from '@portaki/sdk-test-support'
+import {
+  assertGuestSurface,
+  renderGuestModule,
+  renderHostModule,
+} from '@portaki/sdk-test-support'
 
 import moduleDef from './index'
+import { createSectionsTestHostContext } from './test/mock-host-module-context'
 
 describe('@portaki/module-sections', () => {
   it('exposes a valid guest module definition', () => {
     assertGuestSurface(moduleDef)
   })
 
-  it('renders without crashing', async () => {
-    const view =
-      moduleDef.surface === 'host' ? renderHostModule(moduleDef) : renderGuestModule(moduleDef)
+  it('renders guest surface without crashing', async () => {
+    const view = renderGuestModule(moduleDef)
+    await waitFor(() => {
+      expect(view.container).toBeTruthy()
+    })
+    view.unmount()
+  })
+
+  it('renders host surface without crashing', async () => {
+    if (moduleDef.renderHost == null) {
+      return
+    }
+    const view = renderHostModule(moduleDef, createSectionsTestHostContext())
     await waitFor(() => {
       expect(view.container).toBeTruthy()
     })

package/src/{sections-module-definition.ts → sections-module-definition.tsx}

@@ -10,11 +10,14 @@ import {
   timestamptz,
   uuid,
   uuidPrimaryKey,
+  type HostModuleContext,
   type ModuleContext,
   type PortakiFullModule,
 } from '@portaki/sdk'
 import type { ReactNode } from 'react'
 
+import { SectionsHostWorkspace } from './host/SectionsHostWorkspace'
+
 const sectionsSchema = moduleSchema([
   table('items', 't_e_module_sections_item', {
     columns: [
@@ -297,5 +300,6 @@ export function defineSectionsModule(render: (ctx: ModuleContext) => ReactNode):
     },
 
     render,
+    renderHost: (ctx: HostModuleContext) => <SectionsHostWorkspace ctx={ctx} />,
   })
 }

package/src/test/mock-host-module-context.ts

@@ -0,0 +1,79 @@
+import type { HostModuleContext, HostModuleShellComponents } from '@portaki/sdk'
+import { createMockHostModuleContext } from '@portaki/sdk-test-support'
+
+import type { SectionsEditorDesign } from '../host/sections-host.types'
+
+/** Stubs until published `@portaki/sdk-test-support` includes `shell` / `gateway`. */
+export const mockHostShell: HostModuleShellComponents = {
+  NotionLikeEditor: () => null,
+  HostEmptyPlaceholder: () => null,
+  HostUnderlineTabs: () => null,
+  Button: () => null,
+  Input: () => null,
+  Dialog: ({ children }) => children ?? null,
+  DialogContent: ({ children }) => children ?? null,
+  DialogHeader: ({ children }) => children ?? null,
+  DialogTitle: ({ children }) => children ?? null,
+  DialogDescription: ({ children }) => children ?? null,
+  DialogFooter: ({ children }) => children ?? null,
+  cn: (...parts) => parts.filter(Boolean).join(' '),
+  toast: { success: () => {}, error: () => {} },
+  parseTipTapDoc: () => ({ type: 'doc', content: [{ type: 'paragraph' }] }),
+  serializeTipTapDoc: (doc) => JSON.stringify(doc),
+  buildSectionTipTapPreset: () => ({
+    contentFr: { type: 'doc', content: [] },
+    contentEn: { type: 'doc', content: [] },
+  }),
+}
+
+const mockSectionsDesign: SectionsEditorDesign = {
+  id: 'sections-editor-v1',
+  moduleId: 'sections',
+  layout: 'sections-split-panel',
+  gateway: {
+    listQuery: 'sections.list',
+    saveCommand: 'sections.section.save',
+    deleteCommand: 'sections.section.delete',
+    reorderCommand: 'sections.reorder',
+  },
+  createModal: {
+    titleFr: 'Nouvelle section',
+    subtitleFr: 'Modèle',
+    titleFieldLabelFr: 'Titre',
+    titleFieldHintFr: 'Hint',
+    footerHintFr: 'Footer',
+    cancelLabelFr: 'Annuler',
+    submitLabelFr: 'Créer',
+    defaultTemplateId: 'welcome',
+    templates: [],
+  },
+  emptyState: {
+    titleFr: 'Vide',
+    descriptionFr: 'Desc',
+    primaryActionLabelFr: 'Créer',
+  },
+  toasts: {
+    loadError: 'load',
+    saveError: 'save',
+    reorderError: 'reorder',
+    createSuccess: 'created',
+    createError: 'create err',
+    deleteSuccess: 'deleted',
+    deleteError: 'delete err',
+  },
+}
+
+export function createSectionsTestHostContext(
+  overrides: Partial<HostModuleContext> = {},
+): HostModuleContext {
+  const base = createMockHostModuleContext(overrides)
+  return {
+    ...base,
+    design: overrides.design ?? mockSectionsDesign,
+    gateway: overrides.gateway ?? base.gateway ?? {
+      query: async <T,>() => [] as T,
+      command: async () => {},
+    },
+    shell: overrides.shell ?? base.shell ?? mockHostShell,
+  }
+}