@commonpub/layer 0.24.0 → 0.25.0

package/composables/useLayoutAutoSave.ts

@@ -0,0 +1,117 @@
+/**
+ * useLayoutAutoSave — debounced auto-save for the layout editor.
+ *
+ * Phase 3a.6 + session-160 audit polish. Two complementary triggers:
+ *   1. Debounce: watch a dirty flag; on first dirt, wait `debounceMs`
+ *      (default 1500 per docs/plans/layout-and-pages.md §7.13) then
+ *      save. Further edits within the window reset the timer.
+ *   2. Visibility-change flush: when the tab becomes hidden (Cmd+Tab,
+ *      tab close intent, minimize) and the draft is dirty, fire an
+ *      immediate save. This is the safety net for users who edit
+ *      then close the tab during the debounce window.
+ *
+ * Caller (the editor page) owns:
+ *   - the dirty ref (from useLayoutEditor)
+ *   - the save fn (from useLayoutEditor)
+ *   - error/conflict handling — save() throws on 409 and the page
+ *     catches it; auto-save itself just swallows + lets the
+ *     editor.status reflect the result
+ *
+ * Per UX research synthesis (session 160 audit): debounce alone loses
+ * data when the user Cmd-W's during the window; blur alone misses
+ * idle-keyboard edits; both together gives a "nothing was lost"
+ * mental model.
+ *
+ * The composable returns a `cancel()` for tests + manual pause; the
+ * timer is automatically cleared on component unmount.
+ */
+import { onBeforeUnmount, onMounted, watch, type ComputedRef, type Ref } from 'vue';
+
+export interface UseLayoutAutoSaveOptions {
+  /** Reactive dirty flag — when true, schedule a save. */
+  dirty: ComputedRef<boolean> | Ref<boolean>;
+  /** Save function — called on debounce-fire. */
+  save: () => Promise<void>;
+  /** Debounce window in ms. Default 1500. */
+  debounceMs?: number;
+  /** When true, skip scheduling entirely (e.g. user toggled auto-save off). */
+  paused?: Ref<boolean>;
+}
+
+export interface UseLayoutAutoSaveResult {
+  /** Stop the pending timer + ignore subsequent dirt until explicitly resumed. */
+  cancel: () => void;
+}
+
+export function useLayoutAutoSave(opts: UseLayoutAutoSaveOptions): UseLayoutAutoSaveResult {
+  const debounceMs = opts.debounceMs ?? 1500;
+  let timer: ReturnType<typeof setTimeout> | null = null;
+
+  function cancel(): void {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+  }
+
+  watch(
+    opts.dirty,
+    (isDirty) => {
+      cancel();
+      if (!isDirty) return;
+      if (opts.paused?.value) return;
+      timer = setTimeout(() => {
+        timer = null;
+        // Errors are surfaced via the save() side-effects (editor.status,
+        // toasts). Swallow here so the watcher doesn't reject.
+        void opts.save().catch(() => {
+          /* handled by save()'s status setter */
+        });
+      }, debounceMs);
+    },
+    { flush: 'post' },
+  );
+
+  /**
+   * Visibility-change flush: when the tab is being hidden AND the draft
+   * is dirty, cancel the pending debounce and save IMMEDIATELY. This
+   * protects against data loss when the user Cmd+Tab's or closes the
+   * tab during the debounce window.
+   *
+   * `document.visibilityState === 'hidden'` fires reliably across modern
+   * browsers (per CanIUse: 100% support). The save() call is async and
+   * returns a promise that we don't await — the browser may not give
+   * us time to finish, but firing the request is better than not.
+   *
+   * The "REAL safety" path (request that survives page teardown) is
+   * now wired separately: session 162 P2.3 added `editor.flushBeacon()`
+   * (fetch with `keepalive:true`) which the editor page calls from a
+   * `pagehide` listener. visibilitychange is the fast path; pagehide-
+   * +-beacon is the safety net for the actual teardown.
+   */
+  function onVisibilityChange(): void {
+    if (typeof document === 'undefined') return;
+    if (document.visibilityState !== 'hidden') return;
+    if (opts.paused?.value) return;
+    // Only flush if there's a pending dirty save
+    const isDirty = (opts.dirty as { value: boolean }).value;
+    if (!isDirty) return;
+    cancel();
+    void opts.save().catch(() => { /* handled */ });
+  }
+
+  onMounted(() => {
+    if (typeof document !== 'undefined') {
+      document.addEventListener('visibilitychange', onVisibilityChange);
+    }
+  });
+
+  onBeforeUnmount(() => {
+    cancel();
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('visibilitychange', onVisibilityChange);
+    }
+  });
+
+  return { cancel };
+}

package/composables/useLayoutDrag.ts

@@ -0,0 +1,290 @@
+/**
+ * useLayoutDrag — pure drag-drop dispatcher logic.
+ *
+ * Phase 3b/A. Owns the "what to do when X drops on Y" semantics so the
+ * component wiring (`<LayoutRow>` + palette tile in upcoming commits)
+ * stays a thin shell over these pure functions. Two motivations:
+ *
+ *   1. **Testability** — dispatcher behavior is unit-tested with plain
+ *      objects + no dnd-kit infrastructure. The component layer only
+ *      proves `makeDroppable` is called with the right options.
+ *   2. **One source of truth** — when 3b/B adds cross-zone drag + when
+ *      3f adds drag-from-inspector, the same dispatcher routes them.
+ *      No "every component reinvents the drop semantics" drift.
+ *
+ * Drag payload shape: every drag carries `{ kind, ...details }` so the
+ * row's onDrop handler can branch on `kind` without sniffing arbitrary
+ * data. Palette tiles carry the section's registry def; section
+ * instances carry the section + source row id.
+ *
+ * Mutations are applied DIRECTLY to the row.sections array. The editor's
+ * deep watcher on `editor.draft.value` picks them up + bumps dirty +
+ * the existing auto-save composable schedules a save within 1.5s. No
+ * parallel save path — Phase 3b/A kickoff rule.
+ */
+import type { LayoutSection, LayoutRow } from './useLayout';
+import type { SectionDefinition } from '@commonpub/ui';
+import type { IDragEvent } from '@vue-dnd-kit/core';
+
+/* ------------------------------------------------------------------ */
+/* Drag payload taxonomy                                                */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Discriminator on every drag payload. Matched by a fast switch in
+ * `dispatchSectionDrop` — adding a new kind is one literal + one case.
+ */
+export type DragPayloadKind = 'palette-section-spec' | 'section-instance';
+
+/**
+ * Payload carried by a palette tile drag. The tile knows the section's
+ * registry def; the drop handler asks the registry to mint a new
+ * `LayoutSection` from the def's `defaultConfig` + `defaultColSpan`.
+ *
+ * We pass the FULL def (not just `type`) because the registry isn't
+ * trivially accessible from every drop handler — the row may not have
+ * the registry plumbed in. Passing the def avoids an extra dependency.
+ */
+export interface PaletteSectionDragPayload {
+  kind: 'palette-section-spec';
+  /** Section type slug — matches the def's `type`. */
+  sectionType: string;
+  /** Default config + colSpan to mint the new section from. */
+  defaultConfig: Record<string, unknown>;
+  defaultColSpan: number;
+  schemaVersion: number;
+}
+
+/**
+ * Payload carried by a section-instance drag (drag a section from one
+ * row to reorder or move to another row). 3b/A scope is within-row
+ * reorder; 3b/B adds cross-row + cross-zone.
+ *
+ * **The dispatcher MUST look up by `section.id`, not by `section`
+ * reference identity.** The envelope holds a reference at drag-start;
+ * if a concurrent `editor.refresh()` happens mid-drag (another admin's
+ * save + the user clicks "Reload their version" in the conflict modal),
+ * the referenced `section` becomes a phantom. Id-based lookup against
+ * the LIVE `row.sections` array tolerates the swap. Tests cover the
+ * 'section-not-found' noop branch.
+ */
+export interface SectionInstanceDragPayload {
+  kind: 'section-instance';
+  /** The section being dragged. Held by REFERENCE — the dispatcher
+   *  uses `.id` to look up the live position in `row.sections`,
+   *  never the reference directly. See class-comment above. */
+  section: LayoutSection;
+  /** The row this section currently lives in — needed for cross-row
+   *  moves so the dispatcher can remove it from its source. */
+  fromRowId: string;
+}
+
+export type DragPayload = PaletteSectionDragPayload | SectionInstanceDragPayload;
+
+/* ------------------------------------------------------------------ */
+/* Section factory                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Mint a new `LayoutSection` from a registry definition. Uses the
+ * project's `crypto.randomUUID()` idiom (matches packages/server,
+ * layers/base/pages/learn/.../edit.vue). `enabled: true` so a fresh
+ * drop is immediately visible; `responsive: null` defers per-breakpoint
+ * tuning to Phase 3f's inspector.
+ *
+ * Pure — takes a def + returns a section. No mutation of inputs.
+ */
+export function createSectionFromSpec(def: PaletteSectionDragPayload): LayoutSection {
+  return {
+    id: crypto.randomUUID(),
+    order: 0, // server-side write handler renumbers; client value isn't authoritative
+    type: def.sectionType,
+    config: { ...def.defaultConfig },
+    colSpan: def.defaultColSpan,
+    responsive: null,
+    enabled: true,
+    visibility: null,
+    schemaVersion: def.schemaVersion,
+  };
+}
+
+/**
+ * Build a palette drag payload from a registry section def. Called by
+ * `<AdminLayoutsPalette>` when wiring `makeDraggable` on each tile.
+ * Lives here so the drop handler's expectation + the drag source's
+ * production stay in lockstep.
+ */
+export function paletteDragPayload(def: SectionDefinition): PaletteSectionDragPayload {
+  return {
+    kind: 'palette-section-spec',
+    sectionType: def.type,
+    defaultConfig: { ...def.defaultConfig },
+    defaultColSpan: def.defaultColSpan,
+    schemaVersion: def.schemaVersion,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* Insert-index computation                                             */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Where in `row.sections` to insert the dropped item. Read from
+ * dnd-kit's `event.hoveredDraggable` (the section currently under the
+ * cursor inside the row):
+ *
+ *   - No hovered draggable → append to the end (drop on empty area).
+ *   - Hovered draggable with placement.left/top → insert BEFORE it.
+ *   - Hovered draggable with placement.right/bottom → insert AFTER it.
+ *
+ * Rows are horizontal; `left`/`right` are the primary signals.
+ * `top`/`bottom` are checked as fallbacks for vertical-list mode (which
+ * we'll use for cross-row reordering in 3b/B's stacked-zones layout —
+ * the computation is reused there).
+ *
+ * Pure. Takes the event + the fallback length. Returns an integer in
+ * `[0, fallbackLen]` (the half-open range that `Array.prototype.splice`
+ * accepts as an insert position).
+ */
+export function computeInsertIndex(event: IDragEvent, fallbackLen: number): number {
+  const hovered = event.hoveredDraggable;
+  if (!hovered) return fallbackLen; // append
+  const insertBefore = hovered.placement.left || hovered.placement.top;
+  return insertBefore ? hovered.index : hovered.index + 1;
+}
+
+/* ------------------------------------------------------------------ */
+/* Drop dispatcher                                                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Outcome of a dispatched drop — useful for callers that want to
+ * narrate the result (ARIA live region, audit log, telemetry) without
+ * sniffing the row's array.
+ *
+ * Phase 3b/B adds `'moved'` for cross-row + cross-zone. The caller
+ * uses `fromRowId` + `toRowId` to build a moveSectionCommand for the
+ * undo stack + to look up zone slugs for narration.
+ */
+export type DropOutcome =
+  | { kind: 'inserted'; section: LayoutSection; at: number }
+  | { kind: 'reordered'; section: LayoutSection; from: number; to: number }
+  | {
+      kind: 'moved';
+      section: LayoutSection;
+      fromRowId: string;
+      fromIdx: number;
+      fromTotal: number;
+      toRowId: string;
+      toIdx: number;
+      toTotal: number;
+    }
+  | { kind: 'noop'; reason: string };
+
+/**
+ * Context the dispatcher needs for CROSS-ROW operations. Optional so
+ * within-row + palette callers (which don't need to look up other
+ * rows) can still call the dispatcher with a 2-arg signature.
+ *
+ * When `findRow` is omitted OR returns null for the source row, a
+ * cross-row drop falls back to noop (with reason `'no-find-row'` or
+ * `'source-row-not-found'`). This makes the cross-zone wiring an
+ * opt-in: callers in old contexts (single-row tests) still work.
+ */
+export interface DispatchContext {
+  /** Look up a row anywhere in the draft by id. Returns null if the
+   *  row doesn't exist (or the caller chose not to support cross-row). */
+  findRow?: (rowId: string) => LayoutRow | null;
+}
+
+/**
+ * Apply a drop to a row. The row's `sections` array is mutated in
+ * place — the editor's deep watcher picks it up + auto-save fires.
+ *
+ * Phase 3b/B scope:
+ *   - palette-section-spec → splice in a fresh section at the computed
+ *     insert index.
+ *   - section-instance dragged FROM THIS SAME ROW → reorder in place
+ *     via splice-remove + splice-insert (sameList per dnd-kit's model).
+ *   - section-instance dragged FROM A DIFFERENT ROW + ctx.findRow
+ *     provides the source → remove from source, insert into destination
+ *     row. Cross-row + cross-zone share this branch (a "different
+ *     row" may be in another zone).
+ *
+ * Returns a DropOutcome describing what happened. `noop` outcomes have
+ * a `reason` for diagnostics — surfaced in tests + (optionally) audit
+ * logs.
+ */
+export function dispatchSectionDrop(
+  event: IDragEvent,
+  row: LayoutRow,
+  ctx: DispatchContext = {},
+): DropOutcome {
+  const item = event.draggedItems[0]?.item as DragPayload | undefined;
+  if (!item) return { kind: 'noop', reason: 'no-dragged-item' };
+
+  if (item.kind === 'palette-section-spec') {
+    const newSection = createSectionFromSpec(item);
+    const insertAt = computeInsertIndex(event, row.sections.length);
+    row.sections.splice(insertAt, 0, newSection);
+    return { kind: 'inserted', section: newSection, at: insertAt };
+  }
+
+  if (item.kind === 'section-instance') {
+    if (item.fromRowId !== row.id) {
+      // Cross-row drag. Needs the source row to splice out of.
+      // Without ctx.findRow, we can't reach it — fall back to noop.
+      if (!ctx.findRow) {
+        return { kind: 'noop', reason: 'no-find-row' };
+      }
+      const sourceRow = ctx.findRow(item.fromRowId);
+      if (!sourceRow) {
+        return { kind: 'noop', reason: 'source-row-not-found' };
+      }
+      const fromIdx = sourceRow.sections.findIndex((s) => s.id === item.section.id);
+      if (fromIdx === -1) {
+        // The dragged section isn't in the source row — defensive
+        // against a stale payload or concurrent edit.
+        return { kind: 'noop', reason: 'section-not-found' };
+      }
+      const fromTotal = sourceRow.sections.length;
+      // Target index in the DESTINATION row (which is `row`, separate
+      // from source). No adjustment needed — the splice on source
+      // doesn't shift indices in the destination.
+      const targetIdx = computeInsertIndex(event, row.sections.length);
+      const [moved] = sourceRow.sections.splice(fromIdx, 1);
+      if (!moved) return { kind: 'noop', reason: 'section-vanished-mid-splice' };
+      row.sections.splice(targetIdx, 0, moved);
+      return {
+        kind: 'moved',
+        section: moved,
+        fromRowId: sourceRow.id,
+        fromIdx,
+        fromTotal,
+        toRowId: row.id,
+        toIdx: targetIdx,
+        toTotal: row.sections.length,
+      };
+    }
+    const fromIdx = row.sections.findIndex((s) => s.id === item.section.id);
+    if (fromIdx === -1) {
+      // The dragged section isn't in this row's array — defensive
+      // against a stale payload or a concurrent edit that removed it.
+      return { kind: 'noop', reason: 'section-not-found' };
+    }
+    // Compute the target index using the row's CURRENT sections (the
+    // dragged section is still there). After splice-remove the indices
+    // shift down by 1 for positions after fromIdx — adjust on insert.
+    const targetIdx = computeInsertIndex(event, row.sections.length);
+    const [moved] = row.sections.splice(fromIdx, 1);
+    // Adjust if removing the source shifted the target.
+    const adjustedTarget = targetIdx > fromIdx ? targetIdx - 1 : targetIdx;
+    if (!moved) return { kind: 'noop', reason: 'section-vanished-mid-splice' };
+    row.sections.splice(adjustedTarget, 0, moved);
+    return { kind: 'reordered', section: moved, from: fromIdx, to: adjustedTarget };
+  }
+
+  // Exhaustive switch: TS narrows `item` to `never` here. Any new kind
+  // will surface as a compile error → forces an explicit case.
+  return { kind: 'noop', reason: 'unknown-drag-kind' };
+}