@gjermundgaraba-designs/pixel-paper 0.13.0 → 0.14.1

package/src/card/card.ts

@@ -2,6 +2,8 @@ import { Array } from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
 import type { Attributes } from "../attributes/attributes.ts";
+import * as Button from "../button/button.ts";
+import * as Fields from "../fields/fields.ts";
 import * as IconButton from "../iconButton/iconButton.ts";
 import { slotView } from "../slot/slot.ts";
 
@@ -18,11 +20,6 @@ export type ViewConfig<Message> = Readonly<{
   /** Attributes for the close glyph, such as a Dialog's `closeButton` group, which closes it.
    *  The glyph prints when they are given. */
   closeAttributes?: Attributes<Message>;
-  /** The close glyph is held while work the reader may not walk away from runs: it prints
-   *  held (`aria-disabled`), stays in the keyboard and drops `closeAttributes`, so a press does
-   *  nothing. Escape and the veil still send a Dialog's close request, so the parent's update
-   *  leaves that Message out while it holds the glyph (see `Dialog.isCloseRequest`). */
-  isCloseHeld?: boolean;
   /** 440px instead of 680px: confirms, settings, sign-in. */
   isNarrow?: boolean;
   /** The action bar: a 2px ink rule, then these pushed right. Give the default `isDefault`. */
@@ -32,14 +29,16 @@ export type ViewConfig<Message> = Readonly<{
   /** Attributes for the action bar, such as a Dialog's `actionBar` group, which moves focus
    *  between the actions with h, l and the side arrows. */
   actionBarAttributes?: Attributes<Message>;
-  /** Makes the card a form, named by its title, so it is a form landmark; Enter in a field
-   *  submits it, whether or not its submit button is held. While the form's work is saving,
-   *  the parent's update must ignore this Message. */
-  onSubmit?: Message;
 }>;
 
-/** The raised surface: paper in a 2px ink box on the 8px print shadow, under a title bar. */
-export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
+/** A card's parts; a form card holds its close glyph while it sends (`aria-disabled`, in the
+ *  keyboard, its close attributes dropped). */
+type Parts<Message> = ViewConfig<Message> & Readonly<{ isCloseHeld?: boolean }>;
+
+const childrenView = <Message>(
+  config: Parts<Message>,
+  h: HtmlBuilder<Message>,
+): ReadonlyArray<Html> => {
   const {
     title,
     titleAttributes = [],
@@ -47,11 +46,9 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
     body,
     closeAttributes,
     isCloseHeld = false,
-    isNarrow = false,
     actions = [],
     lead = [],
     actionBarAttributes = [],
-    onSubmit,
   } = config;
 
   const titleBar = h.header(
@@ -80,13 +77,116 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
     onNonEmpty: (bar) => [h.div([...actionBarAttributes, h.Class("card-actions")], bar)],
   });
 
-  const children = [titleBar, h.div([h.Class("card-body")], body), ...actionBar];
-  const rootAttributes = [h.Class(isNarrow ? "card narrow" : "card")];
+  return [titleBar, h.div([h.Class("card-body")], body), ...actionBar];
+};
+
+const className = (isNarrow: boolean | undefined): string =>
+  isNarrow === true ? "card narrow" : "card";
+
+/** The raised surface: paper in a 2px ink box on the 8px print shadow, under a title bar. */
+export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html =>
+  h.div([h.Class(className(config.isNarrow))], childrenView(config, h));
+
+// FORM
+
+/** Configuration for rendering a form card with `formView`: a card's, but for its body, its
+ *  close attributes and its actions, which the form fills. `lead` stays the card's: what
+ *  goes before the push, such as a form's own delete. */
+export type FormViewConfig<Message> = Omit<
+  ViewConfig<Message>,
+  "body" | "closeAttributes" | "actions"
+> &
+  Readonly<{
+    /** Unique in the document: the submit button's id is `submitId(id)`. */
+    id: string;
+    /** The form's content, fields and all, in one Fields group that `isBusy` holds. A link in
+     *  it (an ErrorSummary's) stays live. */
+    body: ReadonlyArray<Html | string>;
+    /** The submit button's words. It prints primary, the card's default. */
+    submit: string;
+    /** The cancel button's words, before the submit. It closes through `closeAttributes`. */
+    cancel?: string;
+    /** Attributes for the close glyph and the cancel button, such as a Dialog's `closeButton`
+     *  group, which closes it. The glyph prints when they are given. */
+    closeAttributes?: Attributes<Message>;
+    /** The form's work is running (it sends): the submit button is busy, the close glyph and
+     *  cancel are held without `closeAttributes`, and the body is natively disabled, so
+     *  nothing changes under the send and nothing sends twice. In a Dialog, hold its ways out
+     *  too (`Dialog.setCloseHeld`), and let go of both where the send fails. Enter in a field can submit before the fields are held,
+     *  so the update still ignores `onSubmit` while busy. */
+    isBusy?: boolean;
+    /** The form cannot be sent yet (nothing to send): the submit button is held as a Button
+     *  is, and the fields and cancel stay live. Enter in a field can still submit, so the
+     *  update ignores `onSubmit` while it cannot be sent. */
+    isSubmitDisabled?: boolean;
+    /** Sent when the form submits, by its button or by Enter in a field. */
+    onSubmit: Message;
+  }>;
+
+/** The id of a form card's submit button. A send disables the fields, so focus in one falls
+ *  to the page: the form's update moves it here as it sends, with
+ *  `Focus.Focus({ id: Card.submitId(id) })`. */
+export const submitId = (id: string): string => `${id}-submit`;
+
+/** A card that is a form, named by its title, so a form landmark: its body in one Fields
+ *  group, then cancel and the primary submit button in the action bar. */
+export const formView = <Message>(
+  config: FormViewConfig<Message>,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const {
+    id,
+    title,
+    submit,
+    cancel,
+    closeAttributes,
+    isBusy = false,
+    isSubmitDisabled = false,
+    onSubmit,
+  } = config;
+
+  const cancelButton =
+    cancel === undefined
+      ? []
+      : [
+          Button.view(
+            {
+              label: cancel,
+              isDisabled: isBusy,
+              attributes: isBusy ? [] : (closeAttributes ?? []),
+            },
+            h,
+          ),
+        ];
 
-  return onSubmit === undefined
-    ? h.div(rootAttributes, children)
-    : h.form(
-        [...rootAttributes, h.AriaLabel(title), h.Novalidate(true), h.OnSubmit(onSubmit)],
-        children,
-      );
+  const submitButton = Button.view(
+    {
+      label: submit,
+      variant: "Primary",
+      isDefault: true,
+      isBusy,
+      isDisabled: isSubmitDisabled,
+      type: "submit",
+      attributes: [h.Id(submitId(id))],
+    },
+    h,
+  );
+
+  return h.form(
+    [
+      h.Class(className(config.isNarrow)),
+      h.AriaLabel(title),
+      h.Novalidate(true),
+      h.OnSubmit(onSubmit),
+    ],
+    childrenView(
+      {
+        ...config,
+        body: [Fields.view({ body: config.body, isBusy }, h)],
+        isCloseHeld: isBusy,
+        actions: [...cancelButton, submitButton],
+      },
+      h,
+    ),
+  );
 };

package/src/card/index.ts

@@ -1,2 +1,2 @@
-export { view } from "./card.ts";
-export type { ViewConfig } from "./card.ts";
+export { formView, submitId, view } from "./card.ts";
+export type { FormViewConfig, ViewConfig } from "./card.ts";

package/src/confirmDialog/confirmDialog.ts

@@ -21,13 +21,11 @@ export type Model = typeof Model.Type;
 
 // MESSAGE
 
-/** Union of all Messages a confirm dialog can produce. `RequestedCloseWhileHeld`: Escape or a
- *  press on the veil while `isCloseHeld` is set; nothing follows it. */
+/** Union of all Messages a confirm dialog can produce. */
 export const Message = defineMessageUnion({
   GotDialogMessage: { message: Dialog.Message },
   ClickedConfirm: {},
   ClickedCancel: {},
-  RequestedCloseWhileHeld: {},
 });
 export type Message = typeof Message.Type;
 
@@ -36,7 +34,7 @@ export type Message = typeof Message.Type;
 /** Union of OutMessages a confirm dialog reports. `Confirmed`: the reader pressed the action;
  *  the dialog stays open until the parent calls `close`. `Cancelled`: cancel, Escape or a click
  *  on the veil; the dialog has closed, and whether that also stops work already running is
- *  the parent's to decide. Never reported while `isCloseHeld` is set. */
+ *  the parent's to decide. Never reported while its ways out are held (`setCloseHeld`). */
 export const OutMessage = defineMessageUnion({
   Confirmed: {},
   Cancelled: {},
@@ -73,17 +71,26 @@ export const update = (model: Model, message: Message) =>
     GotDialogMessage: ({ message: dialogMessage }) => dialogFold.update(model, dialogMessage),
     ClickedConfirm: () => ({ model, outMessage: OutMessage.Confirmed() }),
     ClickedCancel: () =>
-      pipe(dialogFold.close(model), Update.withOutMessage(OutMessage.Cancelled())),
-    RequestedCloseWhileHeld: () => ({ model }),
+      Dialog.isCloseHeld(model.dialog)
+        ? { model }
+        : pipe(dialogFold.close(model), Update.withOutMessage(OutMessage.Cancelled())),
   });
 
-/** Opens the confirm dialog: focus starts on the action, or on cancel when it is `isDanger`. */
+/** Opens the confirm dialog with its ways out free: focus starts on the action, or on cancel
+ *  when it is `isDanger`. */
 export const open = (model: Model): Update.Return<Model, Message> => dialogFold.open(model);
 
-/** Closes the confirm dialog without reporting `Cancelled`: call it once confirmed work has
- *  landed. */
+/** Closes the confirm dialog without reporting `Cancelled`, and lets go of a hold: call it
+ *  once confirmed work has landed. */
 export const close = (model: Model): Update.Return<Model, Message> => dialogFold.close(model);
 
+/** Holds cancel, Escape and the veil, or lets them go: while held the dialog stays open and
+ *  reports no `Cancelled`, and cancel prints held (`aria-disabled`, in the keyboard). Hold it
+ *  in the update that starts confirmed work whose failure must land here, and let go in the
+ *  update where the work fails; `close` lets go once it lands. */
+export const setCloseHeld = (model: Model, isHeld: boolean): Model =>
+  modifyFields(model, { dialog: (dialog) => Dialog.setCloseHeld(dialog, isHeld) });
+
 // ACCESSORS
 
 /** The confirm dialog's id, unique in the document. */
@@ -92,6 +99,9 @@ export const id = (model: Model): string => Dialog.id(model.dialog);
 /** Whether the confirm dialog is open. */
 export const isOpen = (model: Model): boolean => Dialog.isOpen(model.dialog);
 
+/** Whether its ways out are held (`setCloseHeld`). */
+export const isCloseHeld = (model: Model): boolean => Dialog.isCloseHeld(model.dialog);
+
 // VIEW
 
 /** Per-render inputs passed to `view` through `h.submodel`'s `viewInputs`. */
@@ -114,35 +124,24 @@ export type ViewInputs = Readonly<{
   isDanger?: boolean;
   /** The confirmed work is running: the confirming button is held (its word stays, the
    *  working cursor prints, a second press does nothing) and keeps focus. Cancel stays live
-   *  unless `isCloseHeld`. */
+   *  unless the dialog's ways out are held (`setCloseHeld`). */
   isBusy?: boolean;
   /** The action cannot run now (nothing is running; it is blocked): the confirming button is
    *  held, `aria-disabled` without the working cursor, and stays in the keyboard, so focus
    *  does not fall to the page. Cancel stays live. */
   isDisabled?: boolean;
-  /** The reader may not walk away from the work running now (a delete whose failure must
-   *  land in this dialog): cancel is held as a Button is (`aria-disabled`, in the keyboard,
-   *  a press does nothing), and Escape and a press on the veil leave the
-   *  dialog open, so it reports no `Cancelled` while this is set. `close` still closes it.
-   *  Usually set with `isBusy`. */
-  isCloseHeld?: boolean;
   /** The page's live region and toasts while this is the topmost open dialog, `undefined`
    *  while it is not (see `Dialog`). */
   toLiveRegionView?: (() => Html) | undefined;
 }>;
 
 const cardView = (
+  model: Model,
   viewInputs: ViewInputs,
   render: Dialog.RenderInfo,
   h: HtmlBuilder<Message>,
 ): Html => {
-  const {
-    isDanger = false,
-    isBusy = false,
-    isDisabled = false,
-    isCloseHeld = false,
-    toDetailView,
-  } = viewInputs;
+  const { isDanger = false, isBusy = false, isDisabled = false, toDetailView } = viewInputs;
 
   const commit = Button.view(
     {
@@ -160,7 +159,7 @@ const cardView = (
     {
       label: "cancel",
       isDefault: isDanger,
-      isDisabled: isCloseHeld,
+      isDisabled: Dialog.isCloseHeld(model.dialog),
       onClick: Message.ClickedCancel(),
       attributes: isDanger ? render.initialFocus : [],
     },
@@ -201,8 +200,8 @@ const cardView = (
  * double-click through.
  *
  * Work that takes a while stays in the dialog: set `isBusy` while it runs, `close` once it
- * has landed, and on failure keep it open with the error in `toDetailView`. Set
- * `isCloseHeld` with it when the reader must stay to see how it ends.
+ * has landed, and on failure keep it open with the error in `toDetailView`. Hold its ways
+ * out with `setCloseHeld` too when the reader must stay to see how it ends.
  */
 export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html =>
   h.submodel({
@@ -213,13 +212,8 @@ export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h
       isAlert: viewInputs.isDanger ?? false,
       hasDescription: true,
       toLiveRegionView: viewInputs.toLiveRegionView,
-      toView: (render) => cardView(viewInputs, render, h),
+      toView: (render) => cardView(model, viewInputs, render, h),
     },
-    // NOTE: while closing is held, Escape and a press on the veil are handed on as
-    // `RequestedCloseWhileHeld` instead of reaching the Dialog.
-    toParentMessage: (message) =>
-      viewInputs.isCloseHeld === true && Dialog.isCloseRequest(message)
-        ? Message.RequestedCloseWhileHeld()
-        : Message.GotDialogMessage({ message }),
+    toParentMessage: (message) => Message.GotDialogMessage({ message }),
   }),
 );

package/src/confirmDialog/index.ts

@@ -5,8 +5,10 @@ export {
   close,
   id,
   init,
+  isCloseHeld,
   isOpen,
   open,
+  setCloseHeld,
   update,
   view,
 } from "./confirmDialog.ts";

package/src/dialog/dialog.ts

@@ -13,9 +13,11 @@ import { foldDialog } from "./fold.ts";
 
 // MODEL
 
-/** Schema for a pixel-paper dialog: the `@foldkit/ui` Dialog it is built on. */
+/** Schema for a pixel-paper dialog: the `@foldkit/ui` Dialog it is built on, and whether its
+ *  ways out are held (`setCloseHeld`). */
 export const Model = Schema.Struct({
   dialog: UiDialog.Model,
+  isCloseHeld: Schema.Boolean,
 });
 export type Model = typeof Model.Type;
 
@@ -54,6 +56,7 @@ export type InitConfig = Readonly<{ id: string }>;
 /** Creates a closed dialog. */
 export const init = (config: InitConfig): Model => ({
   dialog: UiDialog.init({ id: config.id }),
+  isCloseHeld: false,
 });
 
 // ACCESSORS
@@ -64,6 +67,9 @@ export const id = (model: Model): string => model.dialog.id;
 /** Whether the dialog is open. */
 export const isOpen = (model: Model): boolean => model.dialog.isOpen;
 
+/** Whether the dialog's ways out are held (`setCloseHeld`). */
+export const isCloseHeld = (model: Model): boolean => model.isCloseHeld;
+
 // UPDATE
 
 const toOutMessage = UiDialog.OutMessage.match<OutMessage | undefined>({
@@ -79,28 +85,39 @@ const dialogFold = foldDialog(UiDialog, {
   toParentOutMessage: toOutMessage,
 });
 
+// NOTE: @foldkit/ui gap: Dialog has no way to hold a close. Escape, a press on the veil and a
+// control given the `closeButton` group all send `RequestedClose`, so a held dialog reads it
+// by its tag and leaves it out.
+const isHeldClose = (model: Model, message: UiDialog.Message): boolean =>
+  model.isCloseHeld && message._tag === "RequestedClose";
+
 /** Processes a dialog Message and returns the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message) =>
   Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(message, {
-    GotDialogMessage: ({ message: dialogMessage }) => dialogFold.update(model, dialogMessage),
+    GotDialogMessage: ({ message: dialogMessage }) =>
+      isHeldClose(model, dialogMessage) ? { model } : dialogFold.update(model, dialogMessage),
     PressedActionKey: () => ({ model }),
   });
 
-/** Opens the dialog: focus moves to the element given the `initialFocus` group, else to the
- *  first control, and returns to where it was when the dialog closes. */
-export const open = (model: Model): Update.Return<Model, Message> => dialogFold.open(model);
-
-/** Closes the dialog without reporting `Closed`. */
-export const close = (model: Model): Update.Return<Model, Message> => dialogFold.close(model);
-
-// NOTE: @foldkit/ui gap: Dialog takes no input that holds a close. Escape, a press on the
-// veil and a control given the `closeButton` group all send `RequestedClose`, so this reads
-// the Dialog's Message by its tag.
-/** Whether a dialog Message asks to close it: Escape, a press on the veil, or a control given
- *  the `closeButton` group. A parent that holds the dialog open while its work runs leaves
- *  such a Message out of `update`. */
-export const isCloseRequest = (message: Message): boolean =>
-  message._tag === "GotDialogMessage" && message.message._tag === "RequestedClose";
+/** Opens the dialog with its ways out free: focus moves to the element given the
+ *  `initialFocus` group, else to the first control, and returns to where it was when the
+ *  dialog closes. */
+export const open = (model: Model): Update.Return<Model, Message> =>
+  dialogFold.open(modifyFields(model, { isCloseHeld: () => false }));
+
+/** Closes the dialog without reporting `Closed`, and lets go of a hold. */
+export const close = (model: Model): Update.Return<Model, Message> =>
+  dialogFold.close(modifyFields(model, { isCloseHeld: () => false }));
+
+/** Holds the dialog's ways out, or lets them go: while held, Escape, a press on the veil and
+ *  a control given the `closeButton` group leave it open and report no `Closed`, so the
+ *  result of work the reader may not walk away from (a save whose failure must land here)
+ *  lands in it. Hold it in the update that starts the work, and let go in the update where
+ *  the work fails, or the reader is shut in with the failure; `close` lets go once it lands,
+ *  and `open` opens it free.
+ *  Hold the card's own close controls too (`Card.formView`'s `isBusy`). */
+export const setCloseHeld = (model: Model, isHeld: boolean): Model =>
+  modifyFields(model, { isCloseHeld: () => isHeld });
 
 // ACTION BAR KEYS
 
@@ -157,7 +174,7 @@ export const moveActionFocus = (
 
 /** The action bar's keys: h or ←, and l or →, move focus between its actions (see
  *  `moveActionFocus`). Attached by the `actionBar` group. In a Scene, resolve it with
- *  `Message.PressedActionKey`. */
+ *  `sceneMounts`. */
 export const BindActionKeys = Mount.defineStream("BindActionKeys", {
   messages: [Message.PressedActionKey],
   execute: ({ element }) =>
@@ -171,6 +188,18 @@ export const BindActionKeys = Mount.defineStream("BindActionKeys", {
     }),
 });
 
+/** What a parent's Scene resolves an open dialog's Mounts with (`@foldkit/ui`'s resources,
+ *  then the action bar's keys), each with a Message that changes nothing:
+ *  `Scene.Mount.resolveAll(...Dialog.sceneMounts)`. It serves every dialog built on this one
+ *  (ConfirmDialog, KeyHelp, CommandPalette), since a Scene lifts the Messages for it. */
+export const sceneMounts = [
+  // NOTE: @foldkit/ui gap: its Dialog ships no Scene resolution for its resources Mount, so
+  // this test helper builds the child Message the Mount would report
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  [UiDialog.AcquireResources, UiDialog.Message.SucceededAcquireResources()],
+  [BindActionKeys, Message.PressedActionKey({ direction: "Next" })],
+] as const;
+
 // VIEW
 
 /** Attribute groups a dialog hands its content. Spread each onto the element it names; a Card

package/src/dialog/index.ts

@@ -6,9 +6,11 @@ export {
   close,
   id,
   init,
-  isCloseRequest,
+  isCloseHeld,
   isOpen,
   open,
+  sceneMounts,
+  setCloseHeld,
   update,
   view,
 } from "./dialog.ts";

package/src/drag/drag.ts

@@ -0,0 +1,207 @@
+// Shared by Board and Sortable, the two users of @foldkit/ui's DragAndDrop: the phase a drag
+// is in, the DragAndDrop Messages both build, what a press lifts, Escape taken before anything
+// else, the lifted copy's measure, and the closest-centre drop target a sortable resolves for
+// a pointer.
+
+import { DragAndDrop as UiDragAndDrop } from "@foldkit/ui";
+import { Array, Effect, Option, Order, Stream, pipe } from "effect";
+import * as Dom from "foldkit/dom";
+
+// PHASE
+
+/** Where a drag is: nothing pressed, pressed but not yet moved, carried by a pointer, or
+ *  carried by the keyboard. */
+type Phase = "Idle" | "Pressed" | "PointerDragging" | "KeyboardDragging";
+
+// NOTE: @foldkit/ui gap: DragAndDrop has no accessor for which input holds an item.
+// `ghostStyle` is Some only while a pointer drags, so it tells a pointer drag from a keyboard
+// one.
+export const phaseOf = (dragAndDrop: UiDragAndDrop.Model): Phase => {
+  if (Option.isNone(UiDragAndDrop.maybeDraggedItemId(dragAndDrop))) {
+    return "Idle";
+  } else if (!UiDragAndDrop.isDragging(dragAndDrop)) {
+    return "Pressed";
+  } else if (Option.isSome(UiDragAndDrop.ghostStyle(dragAndDrop))) {
+    return "PointerDragging";
+  } else {
+    return "KeyboardDragging";
+  }
+};
+
+/** Whether an item is carried, by a pointer or the keyboard. */
+export const isCarrying = (phase: Phase): boolean =>
+  phase === "PointerDragging" || phase === "KeyboardDragging";
+
+// CHILD MESSAGES
+
+// NOTE: @foldkit/ui gap: DragAndDrop exposes no update capability for a press, a keyboard
+// pick-up, a pointer's move and release, or a cancel, and its `draggable` bundle
+// (`role="option"`, `tabindex`) cannot sit on a grip's button. So Board and Sortable build
+// these child Messages themselves.
+export const pressedDraggable = (
+  fields: Parameters<typeof UiDragAndDrop.Message.PressedDraggable>[0],
+): UiDragAndDrop.Message =>
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  UiDragAndDrop.Message.PressedDraggable(fields);
+
+export const activatedKeyboardDrag = (
+  fields: Parameters<typeof UiDragAndDrop.Message.ActivatedKeyboardDrag>[0],
+): UiDragAndDrop.Message =>
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  UiDragAndDrop.Message.ActivatedKeyboardDrag(fields);
+
+export const movedPointer = (
+  fields: Parameters<typeof UiDragAndDrop.Message.MovedPointer>[0],
+): UiDragAndDrop.Message =>
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  UiDragAndDrop.Message.MovedPointer(fields);
+
+export const releasedPointer = (): UiDragAndDrop.Message =>
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  UiDragAndDrop.Message.ReleasedPointer();
+
+export const cancelledDrag = (): UiDragAndDrop.Message =>
+  // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
+  UiDragAndDrop.Message.CancelledDrag();
+
+// PRESS
+
+/** The main mouse button, the only one that lifts. */
+export const LEFT_BUTTON = 0;
+
+/** What a press inside an item may land on without lifting it: its controls, but for the
+ *  buttons `liftingButtons` (a selector list) names, and anything marked `data-no-lift`. */
+export const innerControls = (liftingButtons: string): string =>
+  [
+    "input",
+    "textarea",
+    "select",
+    "a[href]",
+    '[contenteditable]:not([contenteditable="false"])',
+    `button:not(${liftingButtons})`,
+    "[data-no-lift]",
+  ].join(", ");
+
+// ESCAPE
+
+// NOTE: @foldkit/ui gap: DragAndDrop's own Escape cancels the move and lets the key travel
+// on, to a dialog around the list. Board and Sortable take the key first and stop it.
+/** Takes a plain Escape for `message` and stops it there, so a dialog around the list or the
+ *  page's own key bindings never see it. */
+export const takeEscape = <Message>(
+  event: KeyboardEvent,
+  message: Message,
+): Option.Option<Message> => {
+  if (event.key !== "Escape" || event.isComposing) {
+    return Option.none();
+  }
+
+  event.preventDefault();
+  event.stopPropagation();
+  return Option.some(message);
+};
+
+/** Escape on the window, in the capture phase, as `message`. */
+export const escapeKeys = <Message>(message: Message): Stream.Stream<Message> =>
+  Dom.streamFromEventFilterMap({
+    target: () => window,
+    type: "keydown",
+    filterMapEvent: (event) => takeEscape(event, message),
+    options: { capture: true },
+  });
+
+// LIFTED COPY
+
+/** Sizes the copy that follows the pointer to the element `sourceSelector` finds, and keeps the
+ *  pointer where it pressed that element. */
+export const measureLift = (
+  element: Element,
+  sourceSelector: string,
+  pressX: number,
+  pressY: number,
+): void => {
+  const maybeSource = Option.fromNullishOr(document.querySelector(sourceSelector));
+  if (Option.isSome(maybeSource) && element instanceof HTMLElement) {
+    const rect = maybeSource.value.getBoundingClientRect();
+    element.style.setProperty("--lift-width", `${rect.width}px`);
+    element.style.setProperty("--lift-x", `${rect.left - pressX}px`);
+    element.style.setProperty("--lift-y", `${rect.top - pressY}px`);
+  }
+};
+
+// POINTER TARGET
+
+const ROW_TOLERANCE = 1;
+
+type Box = Readonly<{ top: number; centreX: number; centreY: number }>;
+
+const boxOf = (element: Element): Box => {
+  const rect = element.getBoundingClientRect();
+  return {
+    top: rect.top,
+    centreX: rect.left + rect.width / 2,
+    centreY: rect.top + rect.height / 2,
+  };
+};
+
+const isOnSameRow = (box: Box, other: Box): boolean =>
+  Math.abs(other.top - box.top) < ROW_TOLERANCE;
+
+/**
+ * Where a pointer at (`clientX`, `clientY`) would put the held item among the others in
+ * `container` (its `[data-sortable-id]` items, the held one, `heldId`, left out): before or
+ * after the item whose centre is closest. Where items sit side by side (two share a top, a
+ * wrapping grid, the held one counted) the pointer's side of that centre is read across, and
+ * in a column of rows it is read down, so one reading serves a list and a grid.
+ */
+export const insertionIndex = (
+  container: Element,
+  heldId: string,
+  clientX: number,
+  clientY: number,
+): number => {
+  const items = Array.map(
+    Array.fromIterable(container.querySelectorAll<HTMLElement>("[data-sortable-id]")),
+    (item) => ({ id: item.dataset["sortableId"], box: boxOf(item) }),
+  );
+  // read with the held item in its place: two tiles side by side are a row even while one of
+  // them is held
+  const isTiled = Array.some(items, ({ box }, index) =>
+    Option.exists(Array.get(items, index + 1), (next) => isOnSameRow(box, next.box)),
+  );
+  const boxes = pipe(
+    Array.filter(items, (item) => item.id !== heldId),
+    Array.map(({ box }) => box),
+  );
+  const distance = (box: Box): number => Math.hypot(box.centreX - clientX, box.centreY - clientY);
+
+  const byDistance = Order.mapInput(Order.Number, ({ box }: Readonly<{ box: Box }>) =>
+    distance(box),
+  );
+
+  return Array.match(
+    Array.map(boxes, (box, index) => ({ box, index })),
+    {
+      onEmpty: () => 0,
+      onNonEmpty: (candidates) => {
+        const { box, index } = Array.min(candidates, byDistance);
+        const isAfter = isTiled ? clientX > box.centreX : clientY > box.centreY;
+        return isAfter ? index + 1 : index;
+      },
+    },
+  );
+};
+
+// DRAG STYLES
+
+const DRAGGING_ATTRIBUTE = "data-pixel-paper-dragging";
+
+/** While a pointer presses or carries an item, the page is marked
+ *  (`data-pixel-paper-dragging` on the root), so the stylesheet prints the grabbing cursor and
+ *  holds text selection, with no style element of its own. */
+export const markDragging: Stream.Stream<never> = Stream.callback<never>(() =>
+  Effect.acquireRelease(
+    Effect.sync(() => document.documentElement.setAttribute(DRAGGING_ATTRIBUTE, "")),
+    () => Effect.sync(() => document.documentElement.removeAttribute(DRAGGING_ATTRIBUTE)),
+  ).pipe(Effect.flatMap(() => Effect.never)),
+);