@gjermundgaraba-designs/pixel-paper 0.26.0 → 0.27.0

package/src/toast/stack.ts

@@ -1,60 +1,59 @@
 import { Toast as UiToast } from "@foldkit/ui";
 import { Array, Option, Schema } from "effect";
 
-// PAYLOAD
-
 /** `Ok`: a committed change, in ink, gone after the hold. `Error`: red, and it stays until it
  *  is dismissed or taken back; like every tone it is said politely. `Quiet`: news, nothing
  *  wrong, on the head tint, gone after the hold. */
 export const Tone = Schema.Literals(["Ok", "Error", "Quiet"]);
+
 export type Tone = typeof Tone.Type;
 
 /** One small action on a slip (undo, retry). Pressing it reports `SelectedAction` with its id
  *  and dismisses the slip. */
-export const Action = Schema.Struct({ id: Schema.String, label: Schema.String });
+export const Action = Schema.Struct({
+  id: Schema.String,
+  label: Schema.String,
+});
+
 export type Action = typeof Action.Type;
 
-/** What one slip says. */
 export const Payload = Schema.Struct({
   tone: Tone,
   title: Schema.String,
   maybeBody: Schema.Option(Schema.String),
   maybeAction: Schema.Option(Action),
 });
-export type Payload = typeof Payload.Type;
 
-// STACK
+export type Payload = typeof Payload.Type;
 
 const stack = UiToast.make(Payload);
 
-/** `@foldkit/ui`'s Toast stack, bound to the pixel-paper payload. */
-export const { Entry, Model, Message, OutMessage, init, update, show, dismiss, view } = stack;
+export const {
+  Entry,
+  Model,
+  Message,
+  OutMessage,
+  init,
+  update,
+  show,
+  dismiss,
+  view,
+} = stack;
+
 export type Entry = typeof stack.Entry.Type;
+
 export type Model = typeof stack.Model.Type;
-export type Message = typeof stack.Message.Type;
 
-// NOTE: @foldkit/ui gap: Toast exports no accessor for its entries or for whether one is
-// leaving, and `show` does not return the id it gave the entry it added, so these read its
-// Model: an entry stops showing as its leave starts (its animation's `isShowing`), and `show`
-// appends the entry it adds.
+export type Message = typeof stack.Message.Type;
 
-/** The slips on screen, oldest first: every entry but those already leaving. */
-export const showing = (model: Model): ReadonlyArray<Entry> =>
+export const showing = (model: Model): readonly Entry[] =>
   Array.filter(model.entries, (entry) => entry.animation.isShowing);
 
-/** The id of the entry `show` added last. */
 export const newestId = (model: Model): Option.Option<string> =>
   Option.map(Array.last(model.entries), (entry) => entry.id);
 
-// NOTE: @foldkit/ui gap: Toast has no step that holds or releases a slip from outside, only
-// the pointer's own Messages. `hold` and `release` build those two child Messages, so the
-// pixel-paper stack can hold every slip at once (see `pointerMoved` in toast.ts).
-
-/** Holds a slip's hold, as the pointer resting on it does (`HoveredEntry`). */
 export const hold = (model: Model, entryId: string) =>
   update(model, Message.HoveredEntry({ entryId }));
 
-/** Lets a slip's hold run again from its start, as the pointer leaving it does
- *  (`LeftEntry`). */
 export const release = (model: Model, entryId: string) =>
   update(model, Message.LeftEntry({ entryId }));

package/src/toast/toast.ts

@@ -1,4 +1,13 @@
-import { Array, Duration, Effect, Match, Option, Schema, Stream, pipe } from "effect";
+import {
+  Array,
+  Duration,
+  Effect,
+  Match,
+  Option,
+  Schema,
+  Stream,
+  pipe,
+} from "effect";
 import * as Command from "foldkit/command";
 import * as Dom from "foldkit/dom";
 import type { Html, HtmlBuilder } from "foldkit/html";
@@ -11,14 +20,14 @@ import * as Update from "foldkit/update";
 
 import * as Announcer from "../announcer/announcer.ts";
 import * as Button from "../button/button.ts";
+import { htmlElement } from "../dom/html-element.ts";
 import { Focus } from "../focus/focus.ts";
-import * as IconButton from "../iconButton/iconButton.ts";
+import * as IconButton from "../icon-button/icon-button.ts";
 import { isPlain } from "../keys/keys.ts";
 import * as Notice from "../notice/notice.ts";
 import * as Stack from "./stack.ts";
-import { Action, type Payload, type Tone } from "./stack.ts";
-
-// MODEL
+import { Action } from "./stack.ts";
+import type { Payload, Tone } from "./stack.ts";
 
 /** Schema for the page's toast stack: the `@foldkit/ui` Toast stack it is built on, which
  *  holds the slips, what holds them on screen (the pointer on a slip, the keyboard in the
@@ -29,9 +38,8 @@ export const Model = Schema.Struct({
   isFocusIn: Schema.Boolean,
   maybeReturnFocusId: Schema.Option(Schema.String),
 });
-export type Model = typeof Model.Type;
 
-// MESSAGE
+export type Model = typeof Model.Type;
 
 /** Union of all Messages the toast stack can produce. */
 export const Message = defineMessageUnion({
@@ -46,24 +54,19 @@ export const Message = defineMessageUnion({
   CompletedFocus: {},
   CompletedAnnounceSlip: {},
 });
-export type Message = typeof Message.Type;
 
-// OUT MESSAGE
+export type Message = typeof Message.Type;
 
 /** Union of OutMessages the toast stack reports: a slip's action was pressed (the slip is on
  *  its way out), with the action's id and the slip's. */
 export const OutMessage = defineMessageUnion({
   SelectedAction: { id: Schema.String, entryId: Schema.String },
 });
-export type OutMessage = typeof OutMessage.Type;
 
-// INIT
+export type OutMessage = typeof OutMessage.Type;
 
-/** How long a slip that is not an error stays while nothing holds it: the stylesheet's
- *  `--toast-hold`, which an update cannot read. */
-const HOLD = Duration.seconds(5);
+const TOAST_HOLD = Duration.seconds(5);
 
-/** The most slips that are not errors on screen at once. Errors are not counted. */
 const MOST_SHOWING = 3;
 
 /** Configuration for creating the toast stack with `init`. The `id` must be unique in the
@@ -72,81 +75,100 @@ export type InitConfig = Readonly<{ id: string }>;
 
 /** Creates an empty toast stack. */
 export const init = (config: InitConfig): Model => ({
-  stack: Stack.init({ id: config.id, defaultDuration: HOLD }),
+  stack: Stack.init({ id: config.id, defaultDuration: TOAST_HOLD }),
   isPointerIn: false,
   isFocusIn: false,
   maybeReturnFocusId: Option.none(),
 });
 
-// ACCESSORS
-
 /** The stack's id, unique in the document. */
 export const id = (model: Model): string => model.stack.id;
 
 const isHeld = (model: Model): boolean => model.isPointerIn || model.isFocusIn;
 
-/** The slips on screen, newest last. */
-const slips = (model: Model): ReadonlyArray<Stack.Entry> => Stack.showing(model.stack);
-
-// UPDATE
+const slips = (model: Model): readonly Stack.Entry[] =>
+  Stack.showing(model.stack);
 
 type UpdateReturn = Update.ReturnWithOutMessage<Model, Message, OutMessage>;
+
 type StepReturn = Update.Return<Model, Message>;
 
-// the slips on screen are read from the stack, so one that has left needs nothing more
-const foldStackOutMessage = Stack.OutMessage.match<Update.Step<Model, Message>>({
-  DismissedToast: () => (model) => ({ model }),
-});
+const foldStackOutMessage = Stack.OutMessage.match<Update.Step<Model, Message>>(
+  {
+    DismissedToast: () => (model) => ({ model }),
+  }
+);
 
 const foldConfig = {
   foldOutMessage: foldStackOutMessage,
   read: (model: Model) => Option.some(model.stack),
   write: (model: Model, nextStack: Stack.Model): Model =>
     modifyFields(model, { stack: () => nextStack }),
-  toParentMessage: (message: Stack.Message) => Message.GotStackMessage({ message }),
+  toParentMessage: (message: Stack.Message) =>
+    Message.GotStackMessage({ message }),
 };
 
 const foldStack = Update.foldChild({ update: Stack.update, ...foldConfig });
 
 const stackStep = (
-  apply: (stack: Stack.Model, entryId: string) => ReturnType<typeof Stack.update>,
-  entryId: string,
+  apply: (
+    stack: Stack.Model,
+    entryId: string
+  ) => ReturnType<typeof Stack.update>,
+  entryId: string
 ): Update.Step<Model, Message> =>
-  Update.foldChildStep({ update: (stack: Stack.Model) => apply(stack, entryId), ...foldConfig });
+  Update.foldChildStep({
+    update: (stack: Stack.Model) => apply(stack, entryId),
+    ...foldConfig,
+  });
 
 const dismissStep = (entryId: string): Update.Step<Model, Message> =>
   stackStep(Stack.dismiss, entryId);
 
 const eachSlip = (
   model: Model,
-  apply: (stack: Stack.Model, entryId: string) => ReturnType<typeof Stack.update>,
-  maybeExceptId: Option.Option<string>,
+  apply: (
+    stack: Stack.Model,
+    entryId: string
+  ) => ReturnType<typeof Stack.update>,
+  maybeExceptId: Option.Option<string>
 ): StepReturn =>
   Update.combine(
     model,
     Array.map(
-      Array.filter(slips(model), (slip) => !Option.contains(maybeExceptId, slip.id)),
-      (slip) => stackStep(apply, slip.id),
-    ),
+      Array.filter(
+        slips(model),
+        (slip) => !Option.contains(maybeExceptId, slip.id)
+      ),
+      (slip) => stackStep(apply, slip.id)
+    )
   );
 
-const holdAll = (model: Model): StepReturn => eachSlip(model, Stack.hold, Option.none());
+const holdAll = (model: Model): StepReturn =>
+  eachSlip(model, Stack.hold, Option.none());
 
-const releaseUnlessHeld = (model: Model, maybeExceptId: Option.Option<string>): StepReturn =>
-  isHeld(model) ? holdAll(model) : eachSlip(model, Stack.release, maybeExceptId);
+const releaseUnlessHeld = (
+  model: Model,
+  maybeExceptId: Option.Option<string>
+): StepReturn =>
+  isHeld(model)
+    ? holdAll(model)
+    : eachSlip(model, Stack.release, maybeExceptId);
 
-// NOTE: @foldkit/ui gap: Toast holds one slip while the pointer rests on it, and has no way
-// to hold them all. The pixel-paper stack holds them all while the pointer is on any slip or
-// the keyboard is in the stack, so the pointer's own Messages are followed by holding or
-// releasing every slip (`Stack.hold`, `Stack.release`).
 type PointerMove = Readonly<{ isPointerIn: boolean; entryId: string }>;
 
-const pointerMoved = (stackMessage: Stack.Message): Option.Option<PointerMove> =>
+const pointerMoved = (
+  stackMessage: Stack.Message
+): Option.Option<PointerMove> =>
   Match.value(stackMessage).pipe(
     Match.withReturnType<Option.Option<PointerMove>>(),
-    Match.tag("HoveredEntry", ({ entryId }) => Option.some({ isPointerIn: true, entryId })),
-    Match.tag("LeftEntry", ({ entryId }) => Option.some({ isPointerIn: false, entryId })),
-    Match.orElse(() => Option.none()),
+    Match.tag("HoveredEntry", ({ entryId }) =>
+      Option.some({ isPointerIn: true, entryId })
+    ),
+    Match.tag("LeftEntry", ({ entryId }) =>
+      Option.some({ isPointerIn: false, entryId })
+    ),
+    Match.orElse(() => Option.none())
   );
 
 const holdIfHeld =
@@ -160,8 +182,6 @@ const updateStack = (model: Model, stackMessage: Stack.Message): UpdateReturn =>
     onSome: ({ isPointerIn, entryId }) =>
       Update.combine(modifyFields(model, { isPointerIn: () => isPointerIn }), [
         foldStack(stackMessage),
-        // the stack's own fold already let go of the slip the pointer left, so only the
-        // others are released
         (moved) => releaseUnlessHeld(moved, Option.some(entryId)),
       ]),
   });
@@ -174,17 +194,13 @@ export const FocusSlip = Command.define("FocusSlip", {
   execute: ({ entryId }) =>
     Dom.focus(`#${CSS.escape(entryId)} .toast > .iconbtn`).pipe(
       Effect.ignore,
-      Effect.as(Message.CompletedFocusSlip()),
+      Effect.as(Message.CompletedFocusSlip())
     ),
 });
 
-/** The stack element in the page now: `@foldkit/ui`'s container, which carries the stack's
- *  id. */
 const stackElement = (stackId: string): Option.Option<HTMLElement> =>
-  Option.fromNullishOr(document.getElementById(stackId));
+  htmlElement(`#${CSS.escape(stackId)}`);
 
-// NOTE: @foldkit/ui gap: Toast's container is always a polite live region and cannot be told
-// otherwise, so the stack says a slip and the Announcer only where the stack cannot.
 /**
  * Says a raised slip exactly once. `@foldkit/ui`'s stack is always a polite live region, so a
  * slip added to a stack already on the page is read from there, and this says nothing more. A
@@ -201,31 +217,44 @@ export const AnnounceSlip = Command.define("AnnounceSlip", {
       const maybeBefore = yield* Effect.sync(() => stackElement(stackId));
       yield* Render.afterCommit;
       const maybeAfter = yield* Effect.sync(() => stackElement(stackId));
+
       const isHeardFromStack =
         Option.isSome(maybeBefore) &&
         Option.isSome(maybeAfter) &&
         maybeBefore.value === maybeAfter.value;
+
       if (!isHeardFromStack) {
         yield* Announcer.announce(text);
       }
+
       return Message.CompletedAnnounceSlip();
     }),
 });
 
 type FocusCommand = ReturnType<typeof FocusSlip> | ReturnType<typeof Focus>;
 
-const focusAfter = (model: Model, entryId: string): Option.Option<FocusCommand> => {
+const focusAfter = (
+  model: Model,
+  entryId: string
+): Option.Option<FocusCommand> => {
   const index = Option.getOrElse(
     Array.findFirstIndex(slips(model), (slip) => slip.id === entryId),
-    () => 0,
+    () => 0
   );
+
   const remaining = Array.filter(slips(model), (slip) => slip.id !== entryId);
-  return Option.match(Array.get(remaining, Math.min(index, remaining.length - 1)), {
-    onSome: (slip): Option.Option<FocusCommand> => Option.some(FocusSlip({ entryId: slip.id })),
-    onNone: (): Option.Option<FocusCommand> =>
-      // focus goes back where it came into the stack from, once the last slip has gone
-      Option.map(model.maybeReturnFocusId, (elementId) => Focus({ id: elementId })),
-  });
+
+  return Option.match(
+    Array.get(remaining, Math.min(index, remaining.length - 1)),
+    {
+      onSome: (slip): Option.Option<FocusCommand> =>
+        Option.some(FocusSlip({ entryId: slip.id })),
+      onNone: (): Option.Option<FocusCommand> =>
+        Option.map(model.maybeReturnFocusId, (elementId) =>
+          Focus({ id: elementId })
+        ),
+    }
+  );
 };
 
 const dismissKeepingFocus = (model: Model, entryId: string): StepReturn =>
@@ -245,17 +274,22 @@ const dismissKeepingFocus = (model: Model, entryId: string): StepReturn =>
 /** Processes a toast stack Message and returns the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message) =>
   Message.match<UpdateReturn>(message, {
-    GotStackMessage: ({ message: stackMessage }) => updateStack(model, stackMessage),
+    GotStackMessage: ({ message: stackMessage }) =>
+      updateStack(model, stackMessage),
     FocusedStack: ({ maybeFromId }) =>
       holdAll(
         modifyFields(model, {
           isFocusIn: () => true,
-          maybeReturnFocusId: (returnId) => (model.isFocusIn ? returnId : maybeFromId),
-        }),
+          maybeReturnFocusId: (returnId) =>
+            model.isFocusIn ? returnId : maybeFromId,
+        })
       ),
     BlurredStack: () =>
       model.isFocusIn
-        ? releaseUnlessHeld(modifyFields(model, { isFocusIn: () => false }), Option.none())
+        ? releaseUnlessHeld(
+            modifyFields(model, { isFocusIn: () => false }),
+            Option.none()
+          )
         : { model },
     PressedEscape: () =>
       Option.match(Array.last(slips(model)), {
@@ -264,13 +298,18 @@ export const update = (model: Model, message: Message) =>
       }),
     MovedHost: () =>
       releaseUnlessHeld(
-        modifyFields(model, { isFocusIn: () => false, isPointerIn: () => false }),
-        Option.none(),
+        modifyFields(model, {
+          isFocusIn: () => false,
+          isPointerIn: () => false,
+        }),
+        Option.none()
       ),
     ClickedAction: ({ entryId, action }) =>
       pipe(
         dismissKeepingFocus(model, entryId),
-        Update.withOutMessage(OutMessage.SelectedAction({ id: action.id, entryId })),
+        Update.withOutMessage(
+          OutMessage.SelectedAction({ id: action.id, entryId })
+        )
       ),
     ClickedDismiss: ({ entryId }) => dismissKeepingFocus(model, entryId),
     CompletedFocusSlip: () => ({ model }),
@@ -289,16 +328,23 @@ export type ShowConfig = Readonly<{
 }>;
 
 const oldestCalm = (model: Model): Option.Option<Stack.Entry> => {
-  const calm = Array.filter(slips(model), (slip) => slip.payload.tone !== "Error");
+  const calm = Array.filter(
+    slips(model),
+    (slip) => slip.payload.tone !== "Error"
+  );
+
   return Option.filter(Array.head(calm), () => calm.length >= MOST_SHOWING);
 };
 
 /** What `show` returns: the next Model and Commands, and the new slip's id, to take it back
  *  with `dismiss`. */
-type ShowReturn = Update.Return<Model, Message> & Readonly<{ entryId: string }>;
+export type ShowReturn = Update.Return<Model, Message> &
+  Readonly<{ entryId: string }>;
 
 const spoken = (config: ShowConfig): string =>
-  config.body === undefined ? `${config.title}.` : `${config.title}. ${config.body}`;
+  config.body === undefined
+    ? `${config.title}.`
+    : `${config.title}. ${config.body}`;
 
 /**
  * Raises a slip and says it once (see `AnnounceSlip`). At most `MOST_SHOWING` slips that are
@@ -314,29 +360,42 @@ export const show = (model: Model, config: ShowConfig): ShowReturn => {
     maybeBody: Option.fromNullishOr(config.body),
     maybeAction: Option.fromNullishOr(config.action),
   };
-  const maybeReplaced = Option.filter(oldestCalm(model), () => config.tone !== "Error");
+
+  const maybeReplaced = Option.filter(
+    oldestCalm(model),
+    () => config.tone !== "Error"
+  );
 
   const raised = Update.combine(model, [
-    ...Array.fromOption(Option.map(maybeReplaced, (slip) => dismissStep(slip.id))),
+    ...Array.fromOption(
+      Option.map(maybeReplaced, (slip) => dismissStep(slip.id))
+    ),
     Update.foldChildStep({
       update: (stack: Stack.Model) =>
-        Stack.show(stack, { payload, variant: "Info", sticky: config.tone === "Error" }),
+        Stack.show(stack, {
+          payload,
+          variant: "Info",
+          sticky: config.tone === "Error",
+        }),
       ...foldConfig,
     }),
   ]);
 
-  // the stack's show always adds an entry, so a stack without one is a broken invariant
   const entryId = Option.getOrThrowWith(
     Stack.newestId(raised.model.stack),
-    () => new Error("The toast stack raised no entry."),
+    () => new Error("The toast stack raised no entry.")
   );
+
   const shown = Update.combine(raised.model, [
     holdIfHeld(entryId),
     (stepModel) => ({
       model: stepModel,
-      commands: [AnnounceSlip({ stackId: id(stepModel), text: spoken(config) })],
+      commands: [
+        AnnounceSlip({ stackId: id(stepModel), text: spoken(config) }),
+      ],
     }),
   ]);
+
   return {
     model: shown.model,
     commands: [...(raised.commands ?? []), ...(shown.commands ?? [])],
@@ -348,8 +407,6 @@ export const show = (model: Model, config: ShowConfig): ShowReturn => {
 export const dismiss = (model: Model, entryId: string): StepReturn =>
   dismissKeepingFocus(model, entryId);
 
-// VIEW
-
 const slipView = (entry: Stack.Entry, h: HtmlBuilder<Message>): Html => {
   const { tone, title, maybeBody, maybeAction } = entry.payload;
 
@@ -366,9 +423,9 @@ const slipView = (entry: Stack.Entry, h: HtmlBuilder<Message>): Html => {
               isSmall: true,
               onClick: Message.ClickedAction({ entryId: entry.id, action }),
             },
-            h,
-          ),
-        ),
+            h
+          )
+        )
       ),
       IconButton.view(
         {
@@ -376,9 +433,9 @@ const slipView = (entry: Stack.Entry, h: HtmlBuilder<Message>): Html => {
           label: `Dismiss: ${title}`,
           onClick: Message.ClickedDismiss({ entryId: entry.id }),
         },
-        h,
+        h
       ),
-    ],
+    ]
   );
 };
 
@@ -391,29 +448,36 @@ const isOutside = (stack: Element, target: EventTarget | null): boolean =>
   !(target instanceof Node && stack.contains(target));
 
 const elementId = (target: EventTarget | null): Option.Option<string> =>
-  target instanceof Element && target.id !== "" ? Option.some(target.id) : Option.none();
+  target instanceof Element && target.id !== ""
+    ? Option.some(target.id)
+    : Option.none();
 
 const isEscape = (event: KeyboardEvent): boolean =>
-  event.key === "Escape" && !event.isComposing && !event.defaultPrevented && isPlain(event);
+  event.key === "Escape" &&
+  !event.isComposing &&
+  !event.defaultPrevented &&
+  isPlain(event);
 
-/** Focus coming into the stack, from outside it: where it came from, so it can go back. */
 export const stackFocusIn = (
   stack: Element,
-  event: FocusEvent,
+  event: FocusEvent
 ): Option.Option<typeof Message.FocusedStack.Type> =>
-  Option.liftPredicate(Message.FocusedStack({ maybeFromId: elementId(event.relatedTarget) }), () =>
-    isOutside(stack, event.relatedTarget),
+  Option.liftPredicate(
+    Message.FocusedStack({ maybeFromId: elementId(event.relatedTarget) }),
+    () => isOutside(stack, event.relatedTarget)
   );
 
-/** Focus leaving the stack for somewhere outside it. */
 export const stackFocusOut = (
   stack: Element,
-  event: FocusEvent,
+  event: FocusEvent
 ): Option.Option<typeof Message.BlurredStack.Type> =>
-  Option.liftPredicate(Message.BlurredStack(), () => isOutside(stack, event.relatedTarget));
+  Option.liftPredicate(Message.BlurredStack(), () =>
+    isOutside(stack, event.relatedTarget)
+  );
 
-/** A plain Escape on a slip, not composing and not handled already. */
-export const stackKey = (event: KeyboardEvent): Option.Option<typeof Message.PressedEscape.Type> =>
+export const stackKey = (
+  event: KeyboardEvent
+): Option.Option<typeof Message.PressedEscape.Type> =>
   Option.liftPredicate(Message.PressedEscape(), () => isEscape(event));
 
 /** The stack's focus and keys: focus coming in (and from where) and going out, and Escape
@@ -440,7 +504,7 @@ export const BindStack = Mount.defineStream("BindStack", {
           filterMapEvent: stackKey,
         }),
       ],
-      { concurrency: "unbounded" },
+      { concurrency: "unbounded" }
     ),
 });
 
@@ -459,7 +523,11 @@ export const BindStack = Mount.defineStream("BindStack", {
  */
 export const view = defineView<Model, Message>((model, h): Html =>
   h.div(
-    [h.OnMount(BindStack()), h.OnUnmount(Message.MovedHost()), h.Class("toasts")],
+    [
+      h.OnMount(BindStack()),
+      h.OnUnmount(Message.MovedHost()),
+      h.Class("toasts"),
+    ],
     [
       h.submodel({
         slotId: `${id(model)}-entries`,
@@ -473,8 +541,8 @@ export const view = defineView<Model, Message>((model, h): Html =>
         },
         toParentMessage: (message) => Message.GotStackMessage({ message }),
       }),
-    ],
-  ),
+    ]
+  )
 );
 
 /** What a parent's Scene resolves the stack's Mounts with, each with a Message that changes

package/src/toc/index.ts

@@ -1,2 +1,3 @@
 export { readingPositionEntry, view } from "./toc.ts";
+
 export type { Entry, Level, ReadingPositionConfig, ViewConfig } from "./toc.ts";