@gjermundgaraba-designs/pixel-paper 0.14.1 → 0.16.0

package/src/confirmDialog/index.ts

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

package/src/dialog/dialog.ts

@@ -13,11 +13,9 @@ import { foldDialog } from "./fold.ts";
 
 // MODEL
 
-/** Schema for a pixel-paper dialog: the `@foldkit/ui` Dialog it is built on, and whether its
- *  ways out are held (`setCloseHeld`). */
+/** Schema for a pixel-paper dialog: the `@foldkit/ui` Dialog it is built on. */
 export const Model = Schema.Struct({
   dialog: UiDialog.Model,
-  isCloseHeld: Schema.Boolean,
 });
 export type Model = typeof Model.Type;
 
@@ -56,7 +54,6 @@ 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
@@ -67,9 +64,6 @@ 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>({
@@ -85,39 +79,38 @@ const dialogFold = foldDialog(UiDialog, {
   toParentOutMessage: toOutMessage,
 });
 
+/** What a dialog's update reads from its parent as a Message arrives. */
+export type UpdateContext = Readonly<{
+  /** The reader may not walk away from the work running now (a save whose failure must land
+   *  in this dialog): Escape, a press on the veil and a control given the `closeButton` group
+   *  change nothing and report no `Closed`. Read it from the parent's own state as the
+   *  Message arrives (`isSaving(model)`), so it holds exactly while the work runs, however
+   *  soon after the start a key comes. */
+  isCloseHeld: boolean;
+}>;
+
+const FREE: UpdateContext = { isCloseHeld: false };
+
 // 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";
+const isHeldClose = (context: UpdateContext, message: UiDialog.Message): boolean =>
+  context.isCloseHeld && message._tag === "RequestedClose";
 
 /** Processes a dialog Message and returns the next Model, Commands and OutMessage. */
-export const update = (model: Model, message: Message) =>
+export const update = (model: Model, message: Message, context: UpdateContext = FREE) =>
   Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(message, {
     GotDialogMessage: ({ message: dialogMessage }) =>
-      isHeldClose(model, dialogMessage) ? { model } : dialogFold.update(model, dialogMessage),
+      isHeldClose(context, dialogMessage) ? { model } : dialogFold.update(model, dialogMessage),
     PressedActionKey: () => ({ model }),
   });
 
-/** 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 });
+/** 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);
 
 // ACTION BAR KEYS
 

package/src/dialog/fold.ts

@@ -1,6 +1,8 @@
 import { Option } from "effect";
 import * as Update from "foldkit/update";
 
+import type { UpdateContext } from "./dialog.ts";
+
 // FOLD
 
 type ChildReturn<ChildModel, ChildMessage, ChildOutMessage> = Update.ReturnWithOutMessage<
@@ -15,6 +17,7 @@ type DialogChild<ChildModel, ChildMessage, ChildOutMessage> = Readonly<{
   update: (
     model: ChildModel,
     message: ChildMessage,
+    context: UpdateContext,
   ) => ChildReturn<ChildModel, ChildMessage, ChildOutMessage>;
   open: (model: ChildModel) => ChildReturn<ChildModel, ChildMessage, ChildOutMessage>;
   close: (model: ChildModel) => ChildReturn<ChildModel, ChildMessage, ChildOutMessage>;
@@ -36,6 +39,10 @@ type DialogFoldConfig<
    *  veil, a close button). Without it the dialog's OutMessages report nothing: a parent
    *  that reads `isOpen` when it needs to. */
   toParentOutMessage?: (outMessage: ChildOutMessage) => ParentOutMessage | undefined;
+  /** Whether the dialog's ways out are held, read from the parent's own state as each
+   *  Message arrives (`(model) => model.isSaving`). Free when not given. See
+   *  `Dialog.UpdateContext`. */
+  isCloseHeld?: (model: ParentModel) => boolean;
 }>;
 
 /** The dialog folded into its parent: a dialog Message, and opening and closing it. */
@@ -44,6 +51,14 @@ type DialogFold<ParentModel, ParentMessage, ParentOutMessage, ChildMessage> = Re
     model: ParentModel,
     message: ChildMessage,
   ) => Update.ReturnWithOutMessage<ParentModel, ParentMessage, ParentOutMessage>;
+  /** The update a parent that is itself a dialog (ConfirmDialog) runs with the hold its own
+   *  parent gave it. */
+  updateWith: (
+    context: UpdateContext,
+  ) => (
+    model: ParentModel,
+    message: ChildMessage,
+  ) => Update.ReturnWithOutMessage<ParentModel, ParentMessage, ParentOutMessage>;
   open: (model: ParentModel) => Update.Return<ParentModel, ParentMessage>;
   close: (model: ParentModel) => Update.Return<ParentModel, ParentMessage>;
 }>;
@@ -98,14 +113,18 @@ export const foldDialog = <
   // `RequestedOpen`, which reports `Opened`), and so can its update, so each fold needs a
   // step for an OutMessage. This one keeps the parent's Model: a step reports nothing.
   const foldOutMessage = () => (model: ParentModel) => ({ model });
-  const { toParentOutMessage } = config;
-  const update =
-    toParentOutMessage === undefined
-      ? Update.foldChild({ update: child.update, ...lift, foldOutMessage })
-      : Update.foldChild({ update: child.update, ...lift, toParentOutMessage });
+  const { toParentOutMessage, isCloseHeld = () => false } = config;
+  const updateWith = (context: UpdateContext) => {
+    const childUpdate = (model: ChildModel, message: ChildMessage) =>
+      child.update(model, message, context);
+    return toParentOutMessage === undefined
+      ? Update.foldChild({ update: childUpdate, ...lift, foldOutMessage })
+      : Update.foldChild({ update: childUpdate, ...lift, toParentOutMessage });
+  };
 
   return {
-    update,
+    update: (model, message) => updateWith({ isCloseHeld: isCloseHeld(model) })(model, message),
+    updateWith,
     open: Update.foldChildStep({ update: child.open, ...lift, foldOutMessage }),
     close: Update.foldChildStep({ update: child.close, ...lift, foldOutMessage }),
   };

package/src/dialog/index.ts

@@ -6,13 +6,11 @@ export {
   close,
   id,
   init,
-  isCloseHeld,
   isOpen,
   open,
   sceneMounts,
-  setCloseHeld,
   update,
   view,
 } from "./dialog.ts";
-export type { InitConfig, Placement, RenderInfo, ViewInputs } from "./dialog.ts";
+export type { InitConfig, Placement, RenderInfo, UpdateContext, ViewInputs } from "./dialog.ts";
 export { foldDialog } from "./fold.ts";

package/src/panel/panel.ts

@@ -14,6 +14,9 @@ export type ViewConfig = Readonly<{
   id: string;
   /** Pixel caps in the inverted title bar. */
   title: string;
+  /** A quiet IconButton before the title, such as the grip a Sortable of panels hands each
+   *  panel. On the ink bar it prints as `actions` do. */
+  lead?: ReadonlyArray<Html | string>;
   /** A count or state at the title bar's right. */
   meta?: string;
   /** Small Buttons and IconButtons at the title bar's right end, after the meta. On the ink
@@ -32,7 +35,7 @@ export const titleId = (id: string): string => `${id}-title`;
 /** The unit of the system: paper in a 2px ink box on a 5px print shadow, under a title bar. A
  *  region landmark (`<section>`) named by its `h2` title, keyed by its `id`. */
 export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html => {
-  const { id, title, meta, actions = [], body, foot = [], isFlush = false } = config;
+  const { id, title, lead = [], meta, actions = [], body, foot = [], isFlush = false } = config;
 
   return h.keyed("section")(
     id,
@@ -41,6 +44,7 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
       h.header(
         [h.Class("panel-tb")],
         [
+          ...slotView("span", "panel-lead", lead, h),
           h.h2([h.Id(titleId(id))], [title]),
           ...(meta === undefined ? [] : [h.span([h.Class("meta")], [meta])]),
           ...slotView("span", "panel-acts", actions, h),

package/src/pixel-paper.css

@@ -983,23 +983,32 @@ a.textbtn {
   flex: 1 1 100%;
 }
 
-/* ---------- the panel's title-bar actions ---------- */
+/* ---------- the panel's title-bar lead and actions ---------- */
 
-/* small buttons and icon buttons at the bar's right end; the bar trims its padding around
-   them, as a window's does, so a small button keeps the bar near its one-line height */
-.panel-tb:has(> .panel-acts) {
+/* small buttons and icon buttons at the bar's right end, and an icon button before the
+   title; the bar trims its padding around them, as a window's does, so a small button keeps
+   the bar near its one-line height */
+.panel-tb:has(> :is(.panel-lead, .panel-acts)) {
   align-items: center;
   padding-block: 3px;
-  padding-right: 3px;
   min-height: 31px;
 }
 
-.panel-tb:has(> .panel-acts) h2 {
+.panel-tb:has(> .panel-lead) {
+  padding-left: 3px;
+}
+
+.panel-tb:has(> .panel-acts) {
+  padding-right: 3px;
+}
+
+.panel-tb:has(> :is(.panel-lead, .panel-acts)) h2 {
   flex: 1;
   min-width: 0;
   overflow-wrap: anywhere;
 }
 
+.panel-lead,
 .panel-acts {
   display: inline-flex;
   align-items: center;
@@ -1014,6 +1023,7 @@ a.textbtn {
 
 /* on the ink bar a button prints in paper: an outline, or filled when primary. No print
    shadow (it cannot show on ink), so a press nudges 1px, as a toolbar tool does */
+.panel-lead .btn,
 .panel-acts .btn {
   color: var(--paper);
   background: var(--ink);
@@ -1026,6 +1036,7 @@ a.textbtn {
   background: var(--paper);
 }
 
+.panel-lead .btn:not([aria-disabled="true"]):active,
 .panel-acts .btn:not([aria-disabled="true"]):active {
   transform: translate(1px, 1px);
   box-shadow: none;
@@ -1038,12 +1049,17 @@ a.textbtn {
   opacity: 0.6;
 }
 
-.panel-acts .iconbtn.quiet {
+/* a quiet icon button prints in paper, and a hover cannot darken it to the ink of the bar */
+.panel-lead .iconbtn.quiet,
+.panel-acts .iconbtn.quiet,
+.panel-lead .iconbtn.quiet:hover,
+.panel-acts .iconbtn.quiet:hover {
   color: inherit;
 }
 
 /* the ring sits 4px inside the button in its own text colour, so it reads on an outline and
    on a filled one alike */
+.panel-lead .btn:focus-visible,
 .panel-acts .btn:focus-visible {
   outline-color: currentColor;
   outline-offset: -4px;
@@ -2692,8 +2708,8 @@ dialog.veil:focus {
   opacity: 0.75;
 }
 
-/* a held close glyph fades on the bar, as a held button in a panel's title bar does */
-.card-tb .iconbtn[aria-disabled="true"] {
+/* a held icon button fades on the bar, as a held button in a panel's title bar does */
+:is(.card-tb, .panel-tb) .iconbtn[aria-disabled="true"] {
   opacity: 0.6;
   cursor: default;
 }
@@ -3394,7 +3410,7 @@ dialog.veil:focus {
   bottom: -1px;
 }
 
-.sortable.grid .sortable-item:is(.drop-before, .drop-after)::before {
+.sortable:is(.grid, .panels) .sortable-item:is(.drop-before, .drop-after)::before {
   top: -2px;
   bottom: -2px;
   left: auto;
@@ -3454,6 +3470,67 @@ dialog.veil:focus {
   padding: 0;
 }
 
+/* panels: the parent's own panels, up to three across in the deck's gutter and 300px and up,
+   so two across and then one as the column narrows. A row takes its tallest panel's height,
+   and each panel's foot sits at its bottom */
+.sortable.panels .sortable-items {
+  display: grid;
+  grid-template-columns: repeat(
+    auto-fill,
+    minmax(min(100%, max(300px, (100% - 2 * var(--gap)) / 3)), 1fr)
+  );
+  gap: var(--gap);
+}
+
+.sortable.panels .sortable-item {
+  display: block;
+  padding: 0;
+  border-bottom: 0;
+  background: none;
+}
+
+.sortable.panels .sortable-item.movable:hover {
+  background: none;
+}
+
+.sortable.panels .sortable-body {
+  height: 100%;
+}
+
+.sortable.panels .sortable-body > .panel {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+}
+
+.sortable.panels .sortable-body > .panel > .panel-foot {
+  margin-top: auto;
+}
+
+/* the drop line runs down the middle of the gutter */
+.sortable.panels .sortable-item.drop-before::before {
+  left: calc(var(--gap) / -2 - 1px);
+}
+
+.sortable.panels .sortable-item.drop-after::before {
+  right: calc(var(--gap) / -2 - 1px);
+}
+
+/* the held copy is the panel itself, tinted head and lifted onto the card shadow */
+.sortable.panels .sortable-item.lifted {
+  border: 0;
+  box-shadow: none;
+}
+
+.sortable.panels .lifted .panel {
+  background: var(--head);
+  box-shadow: var(--shadow-card);
+}
+
+.sortable.panels .sortable-slot {
+  padding: 0;
+}
+
 /* while a pointer carries an item, the page grabs and selects nothing */
 :root[data-pixel-paper-dragging] {
   user-select: none;

package/src/sortable/sortable.ts

@@ -565,14 +565,17 @@ export const SizeLiftedItem = Mount.define("SizeLiftedItem", {
 
 // VIEW
 
-/** How the items lay out: a column of rows, or tiles that wrap. */
-export type Layout = "List" | "Grid";
+/** How the items lay out: a column of rows, tiles that wrap, or the parent's own panels. */
+export type Layout = "List" | "Grid" | "Panels";
 
 /** What the list hands `toItemView` for each item. */
 export type ItemRender = Readonly<{
   /** This render is the held copy: hidden from screen readers and inert. Leave out ids and
    *  anything the page must find once. */
   isLifted: boolean;
+  /** The item's grip, for the `"Panels"` layout, where the item places it: in its panel's
+   *  `lead`. The other layouts print it before the item themselves. */
+  grip: Html;
 }>;
 
 /** Per-render inputs passed to `view` through `h.submodel`'s `viewInputs`. The `to*` members
@@ -582,8 +585,12 @@ export type ViewInputs = Readonly<{
   /** Names the list for screen readers. */
   label: string;
   /** `"List"` (the default): rows between 1px rules, for a flush panel. `"Grid"`: tiles that
-   *  wrap, 180px and up. */
+   *  wrap, 180px and up. `"Panels"`: each item is a Panel the parent prints, with `render.grip`
+   *  in its `lead`, up to three across in the deck's gutter, 300px and up. */
   layout?: Layout;
+  /** The reader may look but not reorder, as a read-only sign-in: every grip prints held, as
+   *  while moves are held, and nothing lifts. */
+  isReadOnly?: boolean;
   /** One item's content, beside its grip. Also called for the held copy, with
    *  `render.isLifted`. */
   toItemView: (item: Item, render: ItemRender) => ReadonlyArray<Html>;
@@ -610,6 +617,8 @@ const isLiftingPress = (target: EventTarget | null, pointerType: string): boolea
 
 type ListInfo = Readonly<{
   model: Model;
+  layout: Layout;
+  isMovable: boolean;
   items: ReadonlyArray<Item>;
   maybeDropMark: Option.Option<DropMark>;
   toItemView: (item: Item, render: ItemRender) => ReadonlyArray<Html>;
@@ -624,6 +633,18 @@ const isHeldItem = (model: Model, itemId: string): boolean =>
 const liftedGrip = <ParentMessage>(h: HtmlBuilder<ParentMessage>): Html =>
   h.span([h.Class("iconbtn quiet"), h.AriaHidden(true)], [Glyph.view({ name: "grip" }, h)]);
 
+/** The item's content beside its grip, or, in a layout where the item places its grip,
+ *  alone. */
+const itemContents = <ParentMessage>(
+  info: ListInfo,
+  item: Item,
+  render: ItemRender,
+  h: HtmlBuilder<ParentMessage>,
+): ReadonlyArray<Html> => {
+  const body = h.div([h.Class("sortable-body")], info.toItemView(item, render));
+  return info.layout === "Panels" ? [body] : [render.grip, body];
+};
+
 const liftedView = <ParentMessage>(
   info: ListInfo,
   item: Item,
@@ -631,11 +652,11 @@ const liftedView = <ParentMessage>(
 ): Html =>
   h.div(
     [h.Class("sortable-item lifted")],
-    [liftedGrip(h), h.div([h.Class("sortable-body")], info.toItemView(item, { isLifted: true }))],
+    itemContents(info, item, { isLifted: true, grip: liftedGrip(h) }, h),
   );
 
 const gripView = (info: ListInfo, item: Item, h: HtmlBuilder<Message>): Html => {
-  const { model, items } = info;
+  const { model, isMovable, items } = info;
   const isIdleNow = phaseOf(model.dragAndDrop) === "Idle";
 
   const onGripKey: Attribute<Message> = h.OnKeyDownPreventDefault((key) =>
@@ -654,14 +675,14 @@ const gripView = (info: ListInfo, item: Item, h: HtmlBuilder<Message>): Html =>
       glyph: "grip",
       label: fill(COPY.gripLabel, item.label),
       isQuiet: true,
-      isDisabled: !model.isMovable,
+      isDisabled: !isMovable,
       attributes: [
         h.DataAttribute("draggable-id", itemHook(model, item.id)),
         h.DataAttribute(GRIP_ATTRIBUTE, ""),
         h.AriaRoleDescription("draggable"),
         h.AriaDescribedBy(helpId(model)),
         Button.pressedAttribute(isHeldItem(model, item.id), h),
-        ...(model.isMovable ? [onGripKey] : []),
+        ...(isMovable ? [onGripKey] : []),
       ],
     },
     h,
@@ -673,7 +694,7 @@ const itemAttributes = (
   item: Item,
   h: HtmlBuilder<Message>,
 ): ReadonlyArray<Attribute<Message>> => {
-  const { model, items } = info;
+  const { model, isMovable, items } = info;
   const isIdleNow = phaseOf(model.dragAndDrop) === "Idle";
 
   const onPress = h.OnPointerDown(
@@ -689,10 +710,7 @@ const itemAttributes = (
           items,
         }),
         () =>
-          isIdleNow &&
-          model.isMovable &&
-          button === LEFT_BUTTON &&
-          isLiftingPress(target, pointerType),
+          isIdleNow && isMovable && button === LEFT_BUTTON && isLiftingPress(target, pointerType),
       ),
   );
 
@@ -739,7 +757,7 @@ const dropClass = (info: ListInfo, item: Item): string =>
   );
 
 const itemClass = (info: ListInfo, item: Item): string =>
-  `sortable-item${info.model.isMovable ? " movable" : ""}${isHeldItem(info.model, item.id) ? " drag-dim" : ""}${dropClass(info, item)}`;
+  `sortable-item${info.isMovable ? " movable" : ""}${isHeldItem(info.model, item.id) ? " drag-dim" : ""}${dropClass(info, item)}`;
 
 const itemView = (info: ListInfo, item: Item, h: HtmlBuilder<Message>): Html =>
   h.keyed("li")(
@@ -749,10 +767,7 @@ const itemView = (info: ListInfo, item: Item, h: HtmlBuilder<Message>): Html =>
       ...itemAttributes(info, item, h),
       h.Class(itemClass(info, item)),
     ],
-    [
-      gripView(info, item, h),
-      h.div([h.Class("sortable-body")], info.toItemView(item, { isLifted: false })),
-    ],
+    itemContents(info, item, { isLifted: false, grip: gripView(info, item, h) }, h),
   );
 
 /** The items in order, with the held item's copy where the keyboard would drop it: before the
@@ -819,10 +834,20 @@ const liftedCopyView = (info: ListInfo, h: HtmlBuilder<Message>): ReadonlyArray<
   );
 };
 
+const layoutClass = (layout: Layout): string =>
+  Match.value(layout).pipe(
+    Match.withReturnType<string>(),
+    Match.when("List", () => "sortable"),
+    Match.when("Grid", () => "sortable grid"),
+    Match.when("Panels", () => "sortable panels"),
+    Match.exhaustive,
+  );
+
 /**
- * Items the reader puts in order, as rows or as tiles, built on `@foldkit/ui`'s DragAndDrop:
- * `div.sortable` holding `ul.sortable-items` (named by `label`) of `li.sortable-item`, each its
- * grip and the parent's content. The items are the parent's; a drop reports `Moved`.
+ * Items the reader puts in order, as rows, as tiles or as panels, built on `@foldkit/ui`'s
+ * DragAndDrop: `div.sortable` holding `ul.sortable-items` (named by `label`) of
+ * `li.sortable-item`, each its grip and the parent's content (a panel holds its grip in its
+ * title bar). The items are the parent's; a drop reports `Moved`.
  *
  * A mouse drags an item by its body or its grip; touch takes the grip alone, so a finger on
  * an item scrolls the page; the keyboard takes the grip too: Space or Enter picks the item
@@ -833,11 +858,18 @@ const liftedCopyView = (info: ListInfo, h: HtmlBuilder<Message>): ReadonlyArray<
  * the keys.
  */
 export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { items, label, layout = "List", toItemView } = viewInputs;
-  const info: ListInfo = { model, items, maybeDropMark: dropMarkOf(model), toItemView };
+  const { items, label, layout = "List", isReadOnly = false, toItemView } = viewInputs;
+  const info: ListInfo = {
+    model,
+    layout,
+    isMovable: model.isMovable && !isReadOnly,
+    items,
+    maybeDropMark: dropMarkOf(model),
+    toItemView,
+  };
 
   return h.div(
-    [h.Class(layout === "Grid" ? "sortable grid" : "sortable")],
+    [h.Class(layoutClass(layout))],
     [
       // NOTE: Safari takes list semantics from a list printed without markers, so the list
       // says it is one