efficient-easel 0.0.0 → 0.97.0

package/dist/edit-lock/index.d.ts

@@ -0,0 +1,354 @@
+/**
+ * The edit lock's own words (`efficient-easel/strings`, 0.95.0): how long ago,
+ * and who, when the backend could not say.
+ *
+ * Plain TypeScript with no import, like the module it belongs to. A count that
+ * can be one or many is a function, so a host does its own plural.
+ */
+type LockWords = {
+    /** Under 45 seconds, or a time that is not a number. */
+    justNow: string;
+    /** 1 to 59 minutes. */
+    minutesAgo: (v: {
+        count: number;
+    }) => string;
+    /** An hour or more. */
+    hoursAgo: (v: {
+        count: number;
+    }) => string;
+    /** The person, when the backend sent no name. */
+    someone: string;
+};
+
+/**
+ * Who may WRITE the open document, and what to tell the operator when they may
+ * not — for EVERY editor in the house.
+ *
+ * This module is the merge of two files that had grown side by side and said
+ * the same things in two places (card 11161):
+ *
+ *   * `efficient-admin-portal/src/components/email/campaignEditLock.ts` — the
+ *     campaign designer's copy, which alone had the TAKE-OVER half;
+ *   * `efficient-shop/lib/editor-page-lock.ts` — the storefront editor's copy,
+ *     which alone had the claim/heartbeat driver, the auth-rejection rule and
+ *     the "a template has no lock" rule.
+ *
+ * Neither was a subset of the other, so this file keeps EVERY capability of
+ * both, and both editors now import it instead of carrying a copy.
+ *
+ * TWO INDEPENDENT PROTECTIONS, and it matters which is which:
+ *
+ *   * the SAVE-TIME version check is what actually protects work. The backend
+ *     refuses a document write whose base version has moved on, so no amount of
+ *     client-side confusion can erase a colleague's edits. Nothing here can
+ *     weaken it — the token travels with the write and the server decides.
+ *   * this advisory LOCK only stops two people STARTING, and is soft on
+ *     purpose: it expires, it can always be taken over, and — see
+ *     `accessAfterClaimFailure` — it FAILS OPEN. A lock that could refuse to
+ *     let anybody edit would be worse than no lock at all. A save consults it
+ *     in one case only: a tab somebody TOOK the document from is refused
+ *     (`EDIT_LOCK_TAKEN`, read by `readLockTaken`), so it stops at its next
+ *     save instead of its next heartbeat.
+ *
+ * The backend rule is one rule shared by both (efficient/editlock.py). These
+ * are two CONSUMERS of one server-side contract, which is exactly why one
+ * client module can serve them.
+ *
+ * WHAT IS NOT SHARED, and why there is a factory rather than plain functions:
+ * the two editors talk to the backend through different HTTP clients, so a
+ * failure arrives as an `AxiosError` in one and as an `ApiError` in the other,
+ * and the refused-save payload carries a different `code`. Those two facts —
+ * and nothing else — are handed in by the consumer through `createEditLock`.
+ * The module itself imports no HTTP client and knows about no repo.
+ *
+ * LEAF DISCIPLINE: pure TypeScript. No React, no `document`/`window`, no
+ * dependency at all. `crypto` is touched inside a function, never at module
+ * eval, so a Next server component may import this module safely.
+ */
+
+/** The `edit-lock` body — identical for every editable document. */
+type EditLockBody = {
+    held_by_you: boolean;
+    holder_name: string;
+    client_id: string;
+    last_seen_at: string;
+    seconds_since_seen: number;
+    seconds_since_held: number;
+    heartbeat_seconds: number;
+    expiry_seconds: number;
+};
+/** The other operator, as the notices need to describe them. */
+type LockHolder = {
+    name: string;
+    /** Seconds since their last heartbeat, as the SERVER measured it. */
+    secondsSinceSeen: number;
+    /** Seconds since they TOOK the document, as the SERVER measured it. Not the
+     *  same number: an active holder's heartbeat keeps `secondsSinceSeen` near
+     *  zero, so only this one can say "took over 20 seconds ago". */
+    secondsSinceHeld: number;
+};
+/**
+ * Whether the open document may be written, and why not when it may not.
+ *
+ * `editing` is the ONLY writable state, and `canWriteDocument` is the only place
+ * that says so — so a new state added later is read-only until someone
+ * deliberately makes it writable, rather than writable until someone remembers
+ * to block it.
+ */
+type EditAccess = 
+/** The claim is still in flight. Holding writes for the moment it takes is
+ *  what stops a fast typist's first autosave landing before we know whether
+ *  somebody else is in here. */
+{
+    kind: 'checking';
+}
+/** You hold the document. */
+ | {
+    kind: 'editing';
+}
+/** Somebody else holds it and you have not chosen yet — view, or take over. */
+ | {
+    kind: 'blocked';
+    holder: LockHolder;
+}
+/** You chose to look without touching. */
+ | {
+    kind: 'readonly';
+    holder: LockHolder;
+}
+/** You HAD it and somebody took it. Your work is still on screen. */
+ | {
+    kind: 'takenover';
+    holder: LockHolder;
+};
+/** The one gate on the document write path. */
+declare const canWriteDocument: (access: EditAccess) => boolean;
+/**
+ * The access a freshly opened document starts from.
+ *
+ * A document WITH a lock starts `checking` and the claim answers within a round
+ * trip. One WITHOUT — the storefront's templates — has no claim effect at all,
+ * so `checking` there is not a question awaiting an answer, it is a state
+ * nothing will ever leave, and every write for the rest of the session is
+ * refused: the merchant's edits and, first of all, the pinned Header/Footer seed
+ * that runs in the chrome's mount commit. The editor's MOUNT has always known
+ * this; a document SWITCH did not, which is what card 1096 found.
+ *
+ * Not a loosening of `canWriteDocument`: it says which QUESTION a document opens
+ * with, and a document with no lock was never asking one.
+ */
+declare function accessForNewDocument(hasEditLock: boolean): EditAccess;
+/** The holder named by a state that has one (for the banner / the notices). */
+declare const holderOf: (access: EditAccess) => LockHolder | null;
+/** Read the `edit-lock` body — from a 200 or from a 409's error payload. */
+declare function readLockHolder(data: unknown): LockHolder | null;
+/** The five capabilities Puck's `permissions` prop carries for the canvas. */
+type DocumentPermissions = {
+    edit: boolean;
+    insert: boolean;
+    delete: boolean;
+    duplicate: boolean;
+    drag: boolean;
+};
+/**
+ * The canvas's Puck `permissions`, derived from the write gate.
+ *
+ * BOTH branches name ALL FIVE keys — and that completeness is the whole point,
+ * not tidiness. Puck does not replace this prop when it changes; it MERGES it
+ * over the permissions it already holds (store/slices/permissions.ts,
+ * `useRegisterPermissionsSlice`: `{ ...existingGlobalPermissions, ...prop }`),
+ * and a field's editability is the live `getPermissions().edit`. Puck mounts
+ * while the lock claim is still `checking`, so `canEdit` is false and the store
+ * latches every key false. A PARTIAL writable value (say `{ drag: false }`)
+ * would then merge WITHOUT an `edit` key and leave `edit:false` stuck — every
+ * inspector field disabled for good, even after the claim resolves to
+ * `editing`. Spelling out edit/insert/delete/duplicate on the writable branch
+ * resets them, so the panel comes back the instant `canEdit` flips true.
+ *
+ * `drag` stays false in EITHER state: both editors move blocks with native DnD
+ * rails of their own, so Puck's flaky cross-iframe canvas drag is always off.
+ *
+ * Write safety is unchanged: the `checking` window is still non-editable here,
+ * and the host's own write gate still drops any edit attempted before the claim
+ * resolves, so nothing is saved early.
+ */
+declare const documentPermissions: (canEdit: boolean) => DocumentPermissions;
+
+/**
+ * "just now" / "2 minutes ago" — one phrasing, shared by every notice.
+ *
+ * `words` is the host's language (`useEditorStrings().lock`, 0.95.0); left out,
+ * it is the English it always was. The thresholds are not words and do not
+ * move: under 45 seconds is "just now", then whole minutes, then whole hours.
+ */
+declare function describeAge(seconds: number, words?: LockWords): string;
+/** Names the person, or says so honestly when the backend could not. */
+declare const nameOrSomeone: (name: string, words?: LockWords) => string;
+/**
+ * The identity of THIS editor tab.
+ *
+ * Per-tab, not per-user: it is what lets the backend tell "me, in a second tab"
+ * (take my own lock over silently) from "me, here". Deliberately not persisted —
+ * a reload IS a new editor session, and a remembered id would let a closed tab's
+ * claim look alive.
+ */
+declare function newEditorClientId(): string;
+/**
+ * The `code` of a document write refused because somebody else TOOK the
+ * document from this tab (backend `efficient/editlock.py`,
+ * `EDIT_LOCK_TAKEN_CODE`). The write names its tab with the same `client_id`
+ * its claim sends; a write that does not is never refused this way.
+ *
+ * One code for every document type, unlike the version conflict's: the body
+ * is the `edit-lock` body, which is already the same everywhere.
+ */
+declare const EDIT_LOCK_TAKEN = "edit_lock_taken";
+/** A refused save: the stored document moved on since this editor loaded it. */
+type SaveConflict = {
+    /** Who saved over you. Empty when the backend could not attribute the write. */
+    savedBy: string;
+    /** True when it was YOU, in another tab — never blame a colleague for it. */
+    savedByYou: boolean;
+    secondsAgo: number;
+};
+/**
+ * A write the editor is HOLDING rather than sending, and the two other reasons
+ * it might be held. `onChange` never drops a refused write — the operator's
+ * screen is the only copy of it — so each hold owes a release.
+ */
+type HeldWrite = {
+    /** An unpersisted layout is waiting (the host's pending-data ref). */
+    pending: boolean;
+    /** Autosave paused: the merchant turned writes off, and the pill's resume is
+     *  the only thing that may flush. */
+    autoSaveEnabled: boolean;
+    /** A refused save: their work sits behind a banner and only they decide what
+     *  happens to it. Retrying behind their back is how it gets lost. */
+    saveConflict: boolean;
+};
+/** Everything the claim path reads and drives, passed in rather than imported so
+ *  the path itself can be RUN in a test — a rule that only lives inside a React
+ *  effect is a rule nothing can check. */
+type ClaimBeatDeps = {
+    /** Claim the document (or take it). */
+    claim: (takeover: boolean) => Promise<{
+        heartbeat_seconds: number;
+    }>;
+    /** The effect's cleanup ran: a late answer must not grant a document this
+     *  editor has already left, nor flush one that is no longer open. */
+    cancelled: () => boolean;
+    currentAccess: () => EditAccess;
+    heldWrite: () => HeldWrite;
+    setAccess: (access: EditAccess) => void;
+    /** Send the held write — the host's one write path, never a second one. */
+    releaseHeldWrite: () => void;
+    /** Start the heartbeat that KEEPS the document, at the backend's own interval. */
+    startHeartbeat: (intervalMs: number) => void;
+    /** Stop beating. Called when the SESSION is refused, never when a single
+     *  request fails — see `isAuthRejection`. The effect re-runs and claims again
+     *  the moment a fresh token arrives, so this ends a doomed loop rather than
+     *  ending the editor's hold on the document. */
+    stopHeartbeat: () => void;
+    /** A take-over was granted and nothing of this editor's is waiting to be
+     *  written (`shouldReloadAfterTakeover`): load the stored document if it moved
+     *  since this copy was loaded. Optional — a host without it keeps its copy. */
+    reloadIfMoved?: () => void;
+};
+/**
+ * Must a write held ONLY because the document was not yet writable go out now?
+ *
+ * Keyed on the TRANSITION, not on the current state: `beat` also runs on every
+ * heartbeat, where access is already `editing`. Releasing on "is writable" would
+ * flush the merchant's in-progress edit on every beat and delete the debounce
+ * that keeps whole-document writes rare.
+ *
+ * Exported so the rule has a test of its own, and because it is the one piece of
+ * `makeClaimBeat` a caller can reason about without a driver.
+ */
+declare function shouldReleaseHeldWrite(previous: EditAccess, next: EditAccess, held: HeldWrite): boolean;
+/**
+ * After a take-over was GRANTED, should the host check whether the stored
+ * document moved, and load it if so, before the operator edits?
+ *
+ * The taker's copy is whatever they opened, and the person they took it from
+ * may have saved since — in the seconds before learning they were displaced.
+ * Editing that copy means the taker's first save is refused as "saved
+ * elsewhere". When NOTHING of theirs is waiting to be written, loading the
+ * stored copy costs them nothing: from `blocked` / `readonly` the canvas was
+ * read-only, so there is nothing to lose.
+ *
+ * Never when something IS waiting — the edits a displaced tab held, taken
+ * back with "Take it back". Reloading would throw them away. They go out
+ * instead (`shouldReleaseHeldWrite`), and the version check refuses them if the
+ * other person saved in between. Never with a refused save on screen either:
+ * that notice has its own Reload, and it is the operator's to press.
+ *
+ * Only the question. Whether the version moved is the host's to find out: each
+ * document keeps its version its own way.
+ */
+declare function shouldReloadAfterTakeover(previous: EditAccess, next: EditAccess, held: Pick<HeldWrite, 'pending' | 'saveConflict'>): boolean;
+/**
+ * Has the stored document moved on from the version this copy is based on?
+ *
+ * Both are version tokens exactly as the API served them (`layout_updated_at`,
+ * `design_updated_at`), and a version never goes backwards, so any difference
+ * is a newer write. The instant comparison only stops a copy that is somehow
+ * AHEAD of the stored one from reading as moved. Two writes in the same
+ * millisecond still count as moved: `Date` cannot see microseconds, and an
+ * unneeded reload of an untouched copy costs nothing.
+ */
+declare function documentVersionMoved(stored: string, ours: string): boolean;
+/**
+ * The host's half of a reload after a take-over (`shouldReloadAfterTakeover`):
+ * read the stored version, and reload only if it moved AND nothing of the
+ * operator's is waiting by the time the answer comes back — the canvas opened
+ * the moment the take-over landed, so they may have typed during the read, and
+ * that edit is theirs. Resolves whether it reloaded. A read that fails, or a
+ * version that is not known, keeps the copy: the version check still stands
+ * behind the next save.
+ */
+declare function reloadIfVersionMoved(d: {
+    /** The version this copy is based on. */
+    ours: string | null;
+    /** The version stored now. */
+    stored: () => Promise<string | null>;
+    /** An edit is not on the server yet — read live. */
+    hasPending: () => boolean;
+    reload: () => void;
+}): Promise<boolean>;
+/** A failed request reduced to the only two things any decision here needs. */
+type EditLockFailure = {
+    status: number;
+    data: unknown;
+};
+/**
+ * The two things that genuinely differ between one editor and the next.
+ *
+ * Kept to two on purpose. Anything a THIRD editor would also have to answer
+ * belongs in this module, not in another adapter.
+ */
+type EditLockAdapter = {
+    /**
+     * Pull `{ status, data }` out of whatever this repo's HTTP client threw, or
+     * null when the rejection is not a server answer at all (a dropped socket, a
+     * programming error). Every "fails open" branch below leans on that null.
+     */
+    readFailure: (err: unknown) => EditLockFailure | null;
+    /** The `code` the backend puts in a refused-save body for THIS document type
+     *  — `page_changed_elsewhere`, `campaign_changed_elsewhere`. */
+    conflictCode: string;
+};
+/** The decisions that need the adapter. Everything else above is plain. */
+type EditLock = {
+    accessAfterClaimFailure: (err: unknown) => EditAccess;
+    accessAfterTakeoverFailure: (err: unknown, current: EditAccess) => EditAccess;
+    accessAfterHeartbeatFailure: (err: unknown, current: EditAccess) => EditAccess;
+    isAuthRejection: (err: unknown) => boolean;
+    readSaveConflict: (err: unknown) => SaveConflict | null;
+    readLockTaken: (err: unknown) => LockHolder | null;
+    makeClaimBeat: (deps: ClaimBeatDeps) => (takeover: boolean) => Promise<void>;
+};
+/** Bind the decisions to one editor's HTTP client and document type. */
+declare function createEditLock(adapter: EditLockAdapter): EditLock;
+
+export { type ClaimBeatDeps, type DocumentPermissions, EDIT_LOCK_TAKEN, type EditAccess, type EditLock, type EditLockAdapter, type EditLockBody, type EditLockFailure, type HeldWrite, type LockHolder, type LockWords, type SaveConflict, accessForNewDocument, canWriteDocument, createEditLock, describeAge, documentPermissions, documentVersionMoved, holderOf, nameOrSomeone, newEditorClientId, readLockHolder, reloadIfVersionMoved, shouldReleaseHeldWrite, shouldReloadAfterTakeover };

package/dist/edit-lock/index.js

@@ -0,0 +1 @@
+export{EDIT_LOCK_TAKEN,accessForNewDocument,canWriteDocument,createEditLock,describeAge,documentPermissions,documentVersionMoved,holderOf,nameOrSomeone,newEditorClientId,readLockHolder,reloadIfVersionMoved,shouldReleaseHeldWrite,shouldReloadAfterTakeover}from"../chunk-TDA4HH54.js";import"../chunk-RE4LP46F.js";

package/dist/editor/editor.css

@@ -0,0 +1,58 @@
+/*
+ * efficient-easel/editor — the canvas's own marks (blueprint 5.1): the
+ * lists' empty and selected states, and the outlines over the selected and
+ * hovered block. Puck's `puck.css` drew these until now; the rules follow it.
+ *
+ * The canvas is an iframe of its own, so this sheet must reach it: import it
+ * once in the host, and `CanvasFrame` copies the host's stylesheets into the
+ * frame. Tokens fall back to the shell blue, because the frame's document has
+ * no `.es-editor` root to define them.
+ */
+
+/* The frame's root (CanvasFrame). Puck's `[data-puck-entry]` rule: a stacking
+   context of its own, so a block's z-index stays inside the page. */
+[data-puck-entry] {
+  position: relative;
+  z-index: 0;
+}
+/* A frame that FILLS its parent (`height="fill"`): the page is at least as tall
+   as the frame, as Puck's `#frame-root` was, so a short page's background and
+   its top list reach the bottom of the canvas. `height: 1px` gives the root a
+   height of its own for a list's `height: 100%` to resolve against. Not on an
+   `auto` frame, whose height comes FROM the page: there `100vh` is the frame
+   itself, and the page could never be shorter than the frame again. */
+#frame-root.es-frame-fill {
+  height: 1px;
+  min-height: 100vh;
+}
+
+.es-zone {
+  position: relative;
+  height: 100%;
+  min-height: var(--min-empty-height);
+  width: 100%;
+  outline-offset: -2px;
+}
+.es-zone.has-children {
+  min-height: 0;
+}
+.es-zone:empty,
+.es-zone.is-area-selected:not(.is-root),
+.es-zone.is-hovering-area:not(.is-root) {
+  background: color-mix(in srgb, var(--es-accent, #2563eb) 6%, transparent);
+  outline: 2px dashed color-mix(in srgb, var(--es-accent, #2563eb) 35%, transparent);
+}
+
+.es-canvas-outline {
+  pointer-events: none;
+  box-sizing: border-box;
+  z-index: 2147483000;
+}
+.es-canvas-outline.is-selected {
+  outline: 2px solid var(--es-accent, #2563eb);
+  outline-offset: -1px;
+}
+.es-canvas-outline.is-hover {
+  outline: 1px solid color-mix(in srgb, var(--es-accent, #2563eb) 60%, transparent);
+  outline-offset: -1px;
+}