@gjermundgaraba-designs/pixel-paper 0.26.0 → 0.27.0

package/src/drag/drag.ts

@@ -1,9 +1,3 @@
-// Shared by Board and Sortable, the two users of @foldkit/ui's DragAndDrop, and Reel, which
-// holds its own: the phase a drag is in, what a hold keeps and how a step settles it, the
-// DragAndDrop Messages both build, what a press lifts, Escape taken before anything else, the
-// pressing pointer's events, the lifted copy's measure, and the closest-centre drop target a
-// sortable resolves for a pointer. A splitter's handlers are the Reel's and the Rail's.
-
 import { DragAndDrop as UiDragAndDrop } from "@foldkit/ui";
 import { Array, Effect, Option, Order, Schema, Stream, pipe } from "effect";
 import type * as Command from "foldkit/command";
@@ -14,15 +8,8 @@ import * as Update from "foldkit/update";
 
 import { isPlain } from "../keys/keys.ts";
 
-// 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";
@@ -30,19 +17,14 @@ export const phaseOf = (dragAndDrop: UiDragAndDrop.Model): Phase => {
     return "Pressed";
   } else if (Option.isSome(UiDragAndDrop.ghostStyle(dragAndDrop))) {
     return "PointerDragging";
-  } else {
-    return "KeyboardDragging";
   }
+
+  return "KeyboardDragging";
 };
 
-/** Whether an item is carried, by a pointer or the keyboard. */
 export const isCarrying = (phase: Phase): boolean =>
   phase === "PointerDragging" || phase === "KeyboardDragging";
 
-// HOLD
-
-/** What a Board's and a Sortable's Model share: the DragAndDrop, whether items may move, and
- *  what the list keeps while an item is pressed or held. */
 type Holder = Readonly<{
   dragAndDrop: UiDragAndDrop.Model;
   isMovable: boolean;
@@ -52,45 +34,43 @@ type Holder = Readonly<{
 /** Whether an item is pressed or held. While it is, the arrow keys, Space and Escape belong to
  *  the list: pause the page's own bindings for them. The list takes Escape before anything
  *  else sees it. */
-export const isHolding = (model: Holder): boolean => phaseOf(model.dragAndDrop) !== "Idle";
+export const isHolding = (model: Holder): boolean =>
+  phaseOf(model.dragAndDrop) !== "Idle";
 
-/** Whether a press may lift an item now: items may move and none is pressed or held. */
-export const canLift = (model: Holder): boolean => model.isMovable && !isHolding(model);
+export const canLift = (model: Holder): boolean =>
+  model.isMovable && !isHolding(model);
 
-/** Settles a DragAndDrop step: forgets the held item once it is down, and runs what the step
- *  says (`maybeAnnouncement`) after the step's own Commands. */
 export const settle = <Model extends Holder, Message, OutMessage>(
   step: Update.ReturnWithOutMessage<Model, Message, OutMessage>,
-  maybeAnnouncement: Option.Option<Command.Command<Message>>,
+  maybeAnnouncement: Option.Option<Command.Command<Message>>
 ): Update.ReturnWithOutMessage<Model, Message, OutMessage> =>
   Update.withOutMessage(
     {
-      model: isHolding(step.model) ? step.model : { ...step.model, maybeHeld: Option.none() },
-      commands: [...(step.commands ?? []), ...Array.fromOption(maybeAnnouncement)],
+      model: isHolding(step.model)
+        ? step.model
+        : { ...step.model, maybeHeld: Option.none() },
+      commands: [
+        ...(step.commands ?? []),
+        ...Array.fromOption(maybeAnnouncement),
+      ],
     },
-    step.outMessage,
+    step.outMessage
   );
 
-// 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],
+  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],
+  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],
+  fields: Parameters<typeof UiDragAndDrop.Message.MovedPointer>[0]
 ): UiDragAndDrop.Message =>
   // oxlint-disable-next-line foldkit/no-child-message-construction-in-root
   UiDragAndDrop.Message.MovedPointer(fields);
@@ -103,13 +83,8 @@ 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",
@@ -121,15 +96,9 @@ export const innerControls = (liftingButtons: string): string =>
     "[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,
+  message: Message
 ): Option.Option<Message> => {
   if (event.key !== "Escape" || event.isComposing) {
     return Option.none();
@@ -137,10 +106,10 @@ export const takeEscape = <Message>(
 
   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,
@@ -149,9 +118,9 @@ export const escapeKeys = <Message>(message: Message): Stream.Stream<Message> =>
     options: { capture: true },
   });
 
-/** A list's `escape` Subscription: `escapeKeys` as `message` while an item is pressed or
- *  held. */
-export const escapeSubscriptions = <Model extends Holder, Message>(message: Message) =>
+export const escapeSubscriptions = <Model extends Holder, Message>(
+  message: Message
+) =>
   Subscription.make<Model, Message>()((entry) => ({
     escape: entry(
       { isHolding: Schema.Boolean },
@@ -159,51 +128,40 @@ export const escapeSubscriptions = <Model extends Holder, Message>(message: Mess
         modelToDependencies: (model) => ({ isHolding: isHolding(model) }),
         dependenciesToStream: ({ isHolding: isHoldingNow }) =>
           isHoldingNow ? escapeKeys(message) : Stream.empty,
-      },
+      }
     ),
   }));
 
-// POINTER
-
-/** The moves, release and cancel of the pointer `pointerId`, on the document; another
- *  pointer's are not the drag's. */
 const pressingPointer = (pointerId: number): Stream.Stream<PointerEvent> =>
   Stream.filter(
     Stream.mergeAll(
-      Array.map(["pointermove", "pointerup", "pointercancel"] as const, (type) =>
-        Stream.fromEventListener<PointerEvent>(document, type),
+      Array.map(
+        ["pointermove", "pointerup", "pointercancel"] as const,
+        (type) => Stream.fromEventListener<PointerEvent>(document, type)
       ),
-      { concurrency: "unbounded" },
+      { concurrency: "unbounded" }
     ),
-    (event) => event.pointerId === pointerId,
+    (event) => event.pointerId === pointerId
   );
 
-/** What the pressing pointer `pointerId` does, as Messages: each move, the release and the
- *  browser's cancel. */
 export const pointerMessages = <Message>(
   pointerId: number,
   toMessage: Readonly<{
     moved: (event: PointerEvent) => Message;
     released: (event: PointerEvent) => Message;
     cancelled: () => Message;
-  }>,
+  }>
 ): Stream.Stream<Message> =>
   Stream.map(pressingPointer(pointerId), (event) => {
     if (event.type === "pointermove") {
       return toMessage.moved(event);
     } else if (event.type === "pointerup") {
       return toMessage.released(event);
-    } else {
-      return toMessage.cancelled();
     }
-  });
 
-// SPLITTER
+    return toMessage.cancelled();
+  });
 
-/** A splitter's handlers. The main button of a pointer presses it (`onPress`, while
- *  `isIdle`), and its arrows, unmodified, step it (`onStep`, one way or the other): the side
- *  arrows across a `"vertical"` splitter (it sizes a width), up and down along a
- *  `"horizontal"` one (a height). A modified arrow is the application's. */
 export const splitterAttributes = <Message>(
   config: Readonly<{
     orientation: "vertical" | "horizontal";
@@ -211,39 +169,50 @@ export const splitterAttributes = <Message>(
     onPress: (pointerId: number, clientX: number, clientY: number) => Message;
     onStep: (direction: -1 | 1) => Message;
   }>,
-  h: HtmlBuilder<Message>,
+  h: HtmlBuilder<Message>
 ): ReadonlyArray<Attribute<Message>> => {
   const [less, more] =
-    config.orientation === "vertical" ? ["ArrowLeft", "ArrowRight"] : ["ArrowUp", "ArrowDown"];
+    config.orientation === "vertical"
+      ? ["ArrowLeft", "ArrowRight"]
+      : ["ArrowUp", "ArrowDown"];
+
   return [
     h.AriaOrientation(config.orientation),
     h.OnPointerDown(
-      (_pointerType, button, _screenX, _screenY, _time, clientX, clientY, pointerId) =>
+      (
+        _pointerType,
+        button,
+        _screenX,
+        _screenY,
+        _time,
+        clientX,
+        clientY,
+        pointerId
+      ) =>
         Option.liftPredicate(
           config.onPress(pointerId, clientX, clientY),
-          () => button === LEFT_BUTTON && config.isIdle,
-        ),
+          () => button === LEFT_BUTTON && config.isIdle
+        )
     ),
     h.OnKeyDownPreventDefault((key, modifiers) =>
       Option.liftPredicate(
         config.onStep(key === more ? 1 : -1),
-        () => isPlain(modifiers) && (key === less || key === more),
-      ),
+        () => isPlain(modifiers) && (key === less || key === more)
+      )
     ),
   ];
 };
 
-// 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,
+  pressY: number
 ): void => {
-  const maybeSource = Option.fromNullishOr(document.querySelector(sourceSelector));
+  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`);
@@ -252,14 +221,13 @@ export const measureLift = (
   }
 };
 
-// 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,
@@ -270,36 +238,51 @@ const boxOf = (element: Element): Box => {
 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.
- */
+type Axis = "Across" | "Down";
+
+const readAxis = (boxesWithHeld: readonly Box[]): Axis =>
+  Array.some(boxesWithHeld, (box, index) =>
+    Option.exists(Array.get(boxesWithHeld, index + 1), (next) =>
+      isOnSameRow(box, next)
+    )
+  )
+    ? "Across"
+    : "Down";
+
+const isPastCentre = (
+  axis: Axis,
+  box: Box,
+  clientX: number,
+  clientY: number
+): boolean =>
+  axis === "Across" ? clientX > box.centreX : clientY > box.centreY;
+
 export const insertionIndex = (
   container: Element,
   heldId: string,
   clientX: number,
-  clientY: 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)),
+    Array.fromIterable(
+      container.querySelectorAll<HTMLElement>("[data-sortable-id]")
+    ),
+    (item) => ({ id: item.dataset["sortableId"], box: boxOf(item) })
   );
+
+  const axis = readAxis(Array.map(items, ({ box }) => box));
+
   const boxes = pipe(
     Array.filter(items, (item) => item.id !== heldId),
-    Array.map(({ box }) => box),
+    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),
+  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(
@@ -308,23 +291,23 @@ export const insertionIndex = (
       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;
+
+        return isPastCentre(axis, box, clientX, clientY) ? 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)),
+    Effect.sync(() => {
+      document.documentElement.setAttribute(DRAGGING_ATTRIBUTE, "");
+    }),
+    () =>
+      Effect.sync(() => {
+        document.documentElement.removeAttribute(DRAGGING_ATTRIBUTE);
+      })
+  ).pipe(Effect.flatMap(() => Effect.never))
 );

package/src/{dropZone/dropZone.ts → drop-zone/drop-zone.ts}

@@ -9,24 +9,20 @@ import * as Update from "foldkit/update";
 
 import * as Glyph from "../glyph/glyph.ts";
 
-// MODEL
-
 /** Schema for a drop zone: the `@foldkit/ui` FileDrop it is built on, which knows whether a
  *  file hovers it. */
 export const Model = Schema.Struct({
   fileDrop: UiFileDrop.Model,
 });
-export type Model = typeof Model.Type;
 
-// MESSAGE
+export type Model = typeof Model.Type;
 
 /** Union of all Messages a drop zone can produce. */
 export const Message = defineMessageUnion({
   GotFileDropMessage: { message: UiFileDrop.Message },
 });
-export type Message = typeof Message.Type;
 
-// OUT MESSAGE
+export type Message = typeof Message.Type;
 
 /** Union of OutMessages a drop zone reports: files dropped on it or chosen with its button,
  *  or a drop that held no files (text, a link). */
@@ -34,9 +30,8 @@ export const OutMessage = defineMessageUnion({
   ReceivedFiles: { files: Schema.NonEmptyArray(File.File) },
   RejectedNonFiles: {},
 });
-export type OutMessage = typeof OutMessage.Type;
 
-// INIT
+export type OutMessage = typeof OutMessage.Type;
 
 /** Configuration for creating a drop zone with `init`. The `id` must be unique in the
  *  document: it is the file input's id. */
@@ -47,21 +42,16 @@ export const init = (config: InitConfig): Model => ({
   fileDrop: UiFileDrop.init({ id: config.id }),
 });
 
-// ACCESSORS
-
-// NOTE: @foldkit/ui gap: FileDrop exports no `id` accessor, so this reads its Model's field.
-
 /** The drop zone's id, unique in the document: its file input's id. */
 export const id = (model: Model): string => model.fileDrop.id;
 
-// UPDATE
-
 const foldFileDrop = Update.foldChild({
   update: UiFileDrop.update,
   read: (model: Model) => Option.some(model.fileDrop),
   write: (model: Model, nextFileDrop: UiFileDrop.Model) =>
     modifyFields(model, { fileDrop: () => nextFileDrop }),
-  toParentMessage: (message: UiFileDrop.Message) => Message.GotFileDropMessage({ message }),
+  toParentMessage: (message: UiFileDrop.Message) =>
+    Message.GotFileDropMessage({ message }),
   toParentOutMessage: UiFileDrop.OutMessage.match<OutMessage>({
     ReceivedFiles: ({ files }) => OutMessage.ReceivedFiles({ files }),
     RejectedNonFiles: () => OutMessage.RejectedNonFiles(),
@@ -70,11 +60,13 @@ const foldFileDrop = Update.foldChild({
 
 /** Processes a drop zone Message and returns the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message) =>
-  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(message, {
-    GotFileDropMessage: ({ message: fileDropMessage }) => foldFileDrop(model, fileDropMessage),
-  });
-
-// VIEW
+  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(
+    message,
+    {
+      GotFileDropMessage: ({ message: fileDropMessage }) =>
+        foldFileDrop(model, fileDropMessage),
+    }
+  );
 
 /** Per-render inputs passed to `view` through `h.submodel`'s `viewInputs`. */
 export type ViewInputs = Readonly<{
@@ -86,7 +78,7 @@ export type ViewInputs = Readonly<{
   /** Under the sentence: a word that says what the last drop did. A function because a
    *  Submodel's viewInputs may hold functions only at the top level, and Foldkit runs this one
    *  in the parent's boundary, so a handler in it (an undo) dispatches the parent's Message. */
-  toStatusView?: () => ReadonlyArray<Html>;
+  toStatusView?: () => readonly Html[];
 }>;
 
 /**
@@ -96,25 +88,33 @@ export type ViewInputs = Readonly<{
  * and a sentence, and `label.btn.small` around a visually hidden file input, so the button's
  * word is the input's name.
  */
-export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { title, body = [], toStatusView = () => [] } = viewInputs;
-
-  const toView = (groups: UiFileDrop.FileDropAttributes): Html =>
-    h.div(
-      [...groups.root, h.Class("drop-zone")],
-      [
-        h.span([h.Class("drop-zone-glyph")], [Glyph.view({ name: "upload" }, h)]),
-        h.p([], [h.strong([], [title]), ...body]),
-        ...toStatusView(),
-        h.label([h.Class("btn small")], ["choose files", h.input(groups.input)]),
-      ],
-    );
-
-  return h.submodel({
-    slotId: id(model),
-    model: model.fileDrop,
-    view: UiFileDrop.view,
-    viewInputs: { toView, multiple: true },
-    toParentMessage: (message) => Message.GotFileDropMessage({ message }),
-  });
-});
+export const view = defineView<Model, Message, ViewInputs>(
+  (model, viewInputs, h): Html => {
+    const { title, body = [], toStatusView = () => [] } = viewInputs;
+
+    const toView = (groups: UiFileDrop.FileDropAttributes): Html =>
+      h.div(
+        [...groups.root, h.Class("drop-zone")],
+        [
+          h.span(
+            [h.Class("drop-zone-glyph")],
+            [Glyph.view({ name: "upload" }, h)]
+          ),
+          h.p([], [h.strong([], [title]), ...body]),
+          ...toStatusView(),
+          h.label(
+            [h.Class("btn small")],
+            ["choose files", h.input(groups.input)]
+          ),
+        ]
+      );
+
+    return h.submodel({
+      slotId: id(model),
+      model: model.fileDrop,
+      view: UiFileDrop.view,
+      viewInputs: { toView, multiple: true },
+      toParentMessage: (message) => Message.GotFileDropMessage({ message }),
+    });
+  }
+);

package/src/drop-zone/index.ts

@@ -0,0 +1,11 @@
+export {
+  Message,
+  Model,
+  OutMessage,
+  id,
+  init,
+  update,
+  view,
+} from "./drop-zone.ts";
+
+export type { InitConfig, ViewInputs } from "./drop-zone.ts";