@gjermundgaraba-designs/pixel-paper 0.26.0 → 0.27.0

package/src/tips/tips.ts

@@ -21,28 +21,32 @@ import { defineView } from "foldkit/submodel";
 import * as Subscription from "foldkit/subscription";
 import type * as Update from "foldkit/update";
 
-import { prefixKeys } from "../subscription/prefixKeys.ts";
+import { htmlElement } from "../dom/html-element.ts";
+import { prefixKeys } from "../subscription/prefix-keys.ts";
 
-// MODEL
-
-/** Which side of its control the tip opens on: above, or to the right inside a vertical strip
- *  of tools. */
 const Side = Schema.Literals(["Top", "Right"]);
+
 type Side = typeof Side.Type;
 
 /** What brought the tip: a resting pointer or keyboard focus. */
 export const Trigger = Schema.Literals(["Pointer", "Focus"]);
+
 export type Trigger = typeof Trigger.Type;
 
-/** What a tip says: its control's name, and the key that does the same where the control
- *  names one (`data-tip-key`). */
-const Words = { text: Schema.String, maybeKey: Schema.Option(Schema.String), side: Side };
-type Words = Readonly<{ text: string; maybeKey: Option.Option<string>; side: Side }>;
+const Words = {
+  text: Schema.String,
+  maybeKey: Schema.Option(Schema.String),
+  side: Side,
+};
+
+type Words = Readonly<{
+  text: string;
+  maybeKey: Option.Option<string>;
+  side: Side;
+}>;
+
 const ShownWords = { ...Words, trigger: Trigger };
 
-/** Where the page's tip is. `Cold`: none lately. `Waiting`: a pointer rests on a control, for
- *  a moment first. `Shown`. `Leaving`: the pointer left, with a moment to cross onto the tip.
- *  `Warm`: one just closed, so the next opens at once (sweeping a toolbar reads each name). */
 export const TipState = defineTaggedUnion({
   Cold: {},
   Waiting: Words,
@@ -50,18 +54,18 @@ export const TipState = defineTaggedUnion({
   Leaving: ShownWords,
   Warm: {},
 });
+
 export type TipState = typeof TipState.Type;
 
 /** Schema for the page's one tip layer. `version` counts its waits, and tells the current one
  *  from an earlier one whose Command is still out. */
 export const Model = Schema.Struct({
   id: Schema.String,
-  version: Schema.Number,
+  version: Schema.Finite,
   state: TipState,
 });
-export type Model = typeof Model.Type;
 
-// MESSAGE
+export type Model = typeof Model.Type;
 
 /** Union of all Messages the tip layer can produce. */
 export const Message = defineMessageUnion({
@@ -72,15 +76,14 @@ export const Message = defineMessageUnion({
   BlurredTipTarget: {},
   PressedPointer: {},
   PressedKey: {},
-  CompletedWaitBeforeShowing: { version: Schema.Number },
-  CompletedWaitBeforeHiding: { version: Schema.Number },
-  CompletedWaitBeforeCooling: { version: Schema.Number },
+  CompletedWaitBeforeShowing: { version: Schema.Finite },
+  CompletedWaitBeforeHiding: { version: Schema.Finite },
+  CompletedWaitBeforeCooling: { version: Schema.Finite },
   CompletedShowTip: {},
   CompletedHideTip: {},
 });
-export type Message = typeof Message.Type;
 
-// INIT
+export type Message = typeof Message.Type;
 
 /** Configuration for creating the tip layer with `init`. The `id` is the tip element's. */
 export type InitConfig = Readonly<{ id: string }>;
@@ -92,32 +95,24 @@ export const init = (config: InitConfig): Model => ({
   state: TipState.Cold(),
 });
 
-// ACCESSORS
-
 /** The tip element's id, unique in the document. */
 export const id = (model: Model): string => model.id;
 
-/** What brought the tip up, while it shows: a resting pointer or keyboard focus. */
 const maybeShownTrigger = (model: Model): Option.Option<Trigger> =>
   Match.value(model.state).pipe(
     Match.withReturnType<Option.Option<Trigger>>(),
     Match.tag("Shown", "Leaving", ({ trigger }) => Option.some(trigger)),
-    Match.orElse(() => Option.none()),
+    Match.orElse(() => Option.none())
   );
 
-// COMMAND
-
-/** A pointer rests this long on a control before its tip opens. */
 const REST = Duration.millis(400);
-/** The time a pointer has to cross from a control onto its tip. */
+
 const GRACE = Duration.millis(120);
-/** After one tip closes, the next opens at once for this long. */
+
 const WARMTH = Duration.millis(400);
 
-/** The attribute that holds a control's tip: its accessible name. */
 const TIP_ATTRIBUTE = "data-tip";
 
-/** The attribute that holds the key a control's tip prints after its name. */
 const TIP_KEY_ATTRIBUTE = "data-tip-key";
 
 const TIP_SELECTOR = `[${TIP_ATTRIBUTE}]`;
@@ -125,31 +120,37 @@ const TIP_SELECTOR = `[${TIP_ATTRIBUTE}]`;
 const hasText = (element: HTMLElement, text: string): boolean =>
   element.isConnected && element.getAttribute(TIP_ATTRIBUTE) === text;
 
-/** The control a tip belongs to, found when it opens: the innermost hovered element with
- *  these words, or the focused one, still the keyboard's. */
-const findTipTarget = (trigger: Trigger, text: string): Option.Option<HTMLElement> =>
+const findTipTarget = (
+  trigger: Trigger,
+  text: string
+): Option.Option<HTMLElement> =>
   Match.value(trigger).pipe(
     Match.withReturnType<Option.Option<HTMLElement>>(),
     Match.when("Pointer", () =>
       Array.findLast(
-        Array.fromIterable(document.querySelectorAll<HTMLElement>(`${TIP_SELECTOR}:hover`)),
-        (element) => hasText(element, text),
-      ),
+        Array.fromIterable(
+          document.querySelectorAll<HTMLElement>(`${TIP_SELECTOR}:hover`)
+        ),
+        (element) => hasText(element, text)
+      )
     ),
     Match.when("Focus", () =>
       pipe(
         Option.fromNullishOr(document.activeElement),
         Option.flatMap((element) =>
-          Option.fromNullishOr(element.closest<HTMLElement>(TIP_SELECTOR)),
+          Option.fromNullishOr(element.closest<HTMLElement>(TIP_SELECTOR))
         ),
-        Option.filter((element) => element.matches(":focus-visible") && hasText(element, text)),
-      ),
+        Option.filter(
+          (element) =>
+            element.matches(":focus-visible") && hasText(element, text)
+        )
+      )
     ),
-    Match.exhaustive,
+    Match.exhaustive
   );
 
 const tipElement = (tipId: string): Option.Option<HTMLElement> =>
-  Option.fromNullishOr(document.getElementById(tipId));
+  htmlElement(`#${CSS.escape(tipId)}`);
 
 const hidePopover = (tip: HTMLElement): void => {
   if (tip.matches(":popover-open")) {
@@ -169,16 +170,19 @@ export const ShowTip = Command.define("ShowTip", {
       Effect.andThen(
         Effect.try(() =>
           Option.map(
-            Option.all({ tip: tipElement(tipId), source: findTipTarget(trigger, text) }),
+            Option.all({
+              tip: tipElement(tipId),
+              source: findTipTarget(trigger, text),
+            }),
             ({ tip, source }) => {
               hidePopover(tip);
               tip.showPopover({ source });
-            },
-          ),
-        ),
+            }
+          )
+        )
       ),
       Effect.ignore,
-      Effect.as(Message.CompletedShowTip()),
+      Effect.as(Message.CompletedShowTip())
     ),
 });
 
@@ -189,55 +193,73 @@ export const HideTip = Command.define("HideTip", {
   execute: ({ tipId }) =>
     Effect.try(() => Option.map(tipElement(tipId), hidePopover)).pipe(
       Effect.ignore,
-      Effect.as(Message.CompletedHideTip()),
+      Effect.as(Message.CompletedHideTip())
     ),
 });
 
 /** Waits for a resting pointer. */
 export const WaitBeforeShowing = Command.define("WaitBeforeShowing", {
-  args: { version: Schema.Number },
+  args: { version: Schema.Finite },
   messages: [Message.CompletedWaitBeforeShowing],
   execute: ({ version }) =>
-    Effect.sleep(REST).pipe(Effect.as(Message.CompletedWaitBeforeShowing({ version }))),
+    Effect.sleep(REST).pipe(
+      Effect.as(Message.CompletedWaitBeforeShowing({ version }))
+    ),
 });
 
 /** Waits for a pointer crossing onto the tip. */
 export const WaitBeforeHiding = Command.define("WaitBeforeHiding", {
-  args: { version: Schema.Number },
+  args: { version: Schema.Finite },
   messages: [Message.CompletedWaitBeforeHiding],
   execute: ({ version }) =>
-    Effect.sleep(GRACE).pipe(Effect.as(Message.CompletedWaitBeforeHiding({ version }))),
+    Effect.sleep(GRACE).pipe(
+      Effect.as(Message.CompletedWaitBeforeHiding({ version }))
+    ),
 });
 
 /** Waits out the moment after a tip closes in which the next opens at once. */
 export const WaitBeforeCooling = Command.define("WaitBeforeCooling", {
-  args: { version: Schema.Number },
+  args: { version: Schema.Finite },
   messages: [Message.CompletedWaitBeforeCooling],
   execute: ({ version }) =>
-    Effect.sleep(WARMTH).pipe(Effect.as(Message.CompletedWaitBeforeCooling({ version }))),
+    Effect.sleep(WARMTH).pipe(
+      Effect.as(Message.CompletedWaitBeforeCooling({ version }))
+    ),
 });
 
-// UPDATE
-
 type UpdateReturn = Update.Return<Model, Message>;
 
-const wordsOf = ({ text, maybeKey, side }: Words): Words => ({ text, maybeKey, side });
+const wordsOf = ({ text, maybeKey, side }: Words): Words => ({
+  text,
+  maybeKey,
+  side,
+});
 
 const show = (model: Model, words: Words, trigger: Trigger): UpdateReturn => ({
-  model: modifyFields(model, { state: () => TipState.Shown({ ...wordsOf(words), trigger }) }),
+  model: modifyFields(model, {
+    state: () => TipState.Shown({ ...wordsOf(words), trigger }),
+  }),
   commands: [ShowTip({ tipId: model.id, text: words.text, trigger })],
 });
 
 const hide = (model: Model): UpdateReturn => {
   const nextVersion = Number.increment(model.version);
+
   return {
-    model: modifyFields(model, { version: () => nextVersion, state: () => TipState.Warm() }),
-    commands: [HideTip({ tipId: model.id }), WaitBeforeCooling({ version: nextVersion })],
+    model: modifyFields(model, {
+      version: () => nextVersion,
+      state: () => TipState.Warm(),
+    }),
+    commands: [
+      HideTip({ tipId: model.id }),
+      WaitBeforeCooling({ version: nextVersion }),
+    ],
   };
 };
 
 const wait = (model: Model, words: Words): UpdateReturn => {
   const nextVersion = Number.increment(model.version);
+
   return {
     model: modifyFields(model, {
       version: () => nextVersion,
@@ -247,12 +269,17 @@ const wait = (model: Model, words: Words): UpdateReturn => {
   };
 };
 
-const leave = (model: Model, shown: typeof TipState.Shown.Type): UpdateReturn => {
+const leave = (
+  model: Model,
+  shown: typeof TipState.Shown.Type
+): UpdateReturn => {
   const nextVersion = Number.increment(model.version);
+
   return {
     model: modifyFields(model, {
       version: () => nextVersion,
-      state: () => TipState.Leaving({ ...wordsOf(shown), trigger: shown.trigger }),
+      state: () =>
+        TipState.Leaving({ ...wordsOf(shown), trigger: shown.trigger }),
     }),
     commands: [WaitBeforeHiding({ version: nextVersion })],
   };
@@ -262,7 +289,6 @@ const cool = (model: Model): UpdateReturn => ({
   model: modifyFields(model, { state: () => TipState.Cold() }),
 });
 
-/** Closes what shows, forgets what waits. */
 const dismiss = (model: Model): UpdateReturn =>
   TipState.match<UpdateReturn>(model.state, {
     Cold: () => ({ model }),
@@ -275,13 +301,16 @@ const dismiss = (model: Model): UpdateReturn =>
 const entered = (model: Model, words: Words): UpdateReturn =>
   TipState.match<UpdateReturn>(model.state, {
     Cold: () => wait(model, words),
-    Waiting: (waiting) => (waiting.text === words.text ? { model } : wait(model, words)),
-    Shown: (shown) => (shown.text === words.text ? { model } : show(model, words, "Pointer")),
+    Waiting: (waiting) =>
+      waiting.text === words.text ? { model } : wait(model, words),
+    Shown: (shown) =>
+      shown.text === words.text ? { model } : show(model, words, "Pointer"),
     Leaving: (leaving) =>
       leaving.text === words.text
         ? {
             model: modifyFields(model, {
-              state: () => TipState.Shown({ ...wordsOf(words), trigger: leaving.trigger }),
+              state: () =>
+                TipState.Shown({ ...wordsOf(words), trigger: leaving.trigger }),
             }),
           }
         : show(model, words, "Pointer"),
@@ -297,9 +326,10 @@ export const update = (model: Model, message: Message) =>
         model.state,
         {
           Waiting: () => cool(model),
-          Shown: (shown) => (shown.trigger === "Pointer" ? leave(model, shown) : { model }),
+          Shown: (shown) =>
+            shown.trigger === "Pointer" ? leave(model, shown) : { model },
         },
-        () => ({ model }),
+        () => ({ model })
       ),
     EnteredTip: () =>
       TipState.matchOrElse<UpdateReturn>(
@@ -307,11 +337,15 @@ export const update = (model: Model, message: Message) =>
         {
           Leaving: (leaving) => ({
             model: modifyFields(model, {
-              state: () => TipState.Shown({ ...wordsOf(leaving), trigger: leaving.trigger }),
+              state: () =>
+                TipState.Shown({
+                  ...wordsOf(leaving),
+                  trigger: leaving.trigger,
+                }),
             }),
           }),
         },
-        () => ({ model }),
+        () => ({ model })
       ),
     FocusedTipTarget: (words) => show(model, wordsOf(words), "Focus"),
     BlurredTipTarget: () => dismiss(model),
@@ -322,28 +356,30 @@ export const update = (model: Model, message: Message) =>
         model.state,
         {
           Waiting: (waiting) =>
-            model.version === version ? show(model, wordsOf(waiting), "Pointer") : { model },
+            model.version === version
+              ? show(model, wordsOf(waiting), "Pointer")
+              : { model },
         },
-        () => ({ model }),
+        () => ({ model })
       ),
     CompletedWaitBeforeHiding: ({ version }) =>
       TipState.matchOrElse<UpdateReturn>(
         model.state,
-        { Leaving: () => (model.version === version ? hide(model) : { model }) },
-        () => ({ model }),
+        {
+          Leaving: () => (model.version === version ? hide(model) : { model }),
+        },
+        () => ({ model })
       ),
     CompletedWaitBeforeCooling: ({ version }) =>
       TipState.matchOrElse<UpdateReturn>(
         model.state,
         { Warm: () => (model.version === version ? cool(model) : { model }) },
-        () => ({ model }),
+        () => ({ model })
       ),
     CompletedShowTip: () => ({ model }),
     CompletedHideTip: () => ({ model }),
   });
 
-// SUBSCRIPTION
-
 type TargetMessage =
   | typeof Message.EnteredTipTarget.Type
   | typeof Message.LeftTipTarget.Type
@@ -351,8 +387,6 @@ type TargetMessage =
 
 type TipTarget = Words & Readonly<{ element: HTMLElement }>;
 
-/** A control in a vertical strip of tools, or set in vertical writing (a folded rail's title
- *  bar), takes its tip at its side, where the tip would cover the next tool or the top bar. */
 const sideOf = (element: Element): Side =>
   element.closest('[aria-orientation="vertical"]') === null &&
   !getComputedStyle(element).writingMode.startsWith("vertical")
@@ -361,30 +395,39 @@ const sideOf = (element: Element): Side =>
 
 const tipTargetOf = (target: EventTarget | null): Option.Option<TipTarget> =>
   pipe(
-    Option.liftPredicate(target, (node): node is Element => node instanceof Element),
-    Option.flatMap((element) => Option.fromNullishOr(element.closest<HTMLElement>(TIP_SELECTOR))),
+    Option.liftPredicate(
+      target,
+      (node): node is Element => node instanceof Element
+    ),
     Option.flatMap((element) =>
-      Option.map(Option.fromNullishOr(element.getAttribute(TIP_ATTRIBUTE)), (text) => ({
-        element,
-        text,
-        maybeKey: Option.fromNullishOr(element.getAttribute(TIP_KEY_ATTRIBUTE)),
-        side: sideOf(element),
-      })),
+      Option.fromNullishOr(element.closest<HTMLElement>(TIP_SELECTOR))
     ),
+    Option.flatMap((element) =>
+      Option.map(
+        Option.fromNullishOr(element.getAttribute(TIP_ATTRIBUTE)),
+        (text) => ({
+          element,
+          text,
+          maybeKey: Option.fromNullishOr(
+            element.getAttribute(TIP_KEY_ATTRIBUTE)
+          ),
+          side: sideOf(element),
+        })
+      )
+    )
   );
 
-/** What a pointer arriving over `target` means for the tip: over a control with a tip, over
- *  the tip itself, or over neither. Touch never opens a tip. */
 export const pointerOverMessage = (
   tipId: string,
-  event: PointerEvent,
+  event: PointerEvent
 ): Option.Option<TargetMessage> => {
   if (event.pointerType === "touch") {
     return Option.none();
   }
 
   const isOverTip =
-    event.target instanceof Element && event.target.closest(`#${CSS.escape(tipId)}`) !== null;
+    event.target instanceof Element &&
+    event.target.closest(`#${CSS.escape(tipId)}`) !== null;
 
   if (isOverTip) {
     return Option.some(Message.EnteredTip());
@@ -394,46 +437,61 @@ export const pointerOverMessage = (
     Option.match(tipTargetOf(event.target), {
       onNone: () => Message.LeftTipTarget(),
       onSome: (target) => Message.EnteredTipTarget(wordsOf(target)),
-    }),
+    })
   );
 };
 
-/** What focus arriving on `target` means for the tip: keyboard focus (`:focus-visible`) on a
- *  control with a tip shows it; any other focus says nothing. */
 const focusInMessage = (event: FocusEvent): Option.Option<Message> =>
   Option.map(
-    Option.filter(tipTargetOf(event.target), ({ element }) => element.matches(":focus-visible")),
-    (target) => Message.FocusedTipTarget(wordsOf(target)),
+    Option.filter(tipTargetOf(event.target), ({ element }) =>
+      element.matches(":focus-visible")
+    ),
+    (target) => Message.FocusedTipTarget(wordsOf(target))
   );
 
-/** Focus leaving a control with a tip, not into a part of itself, closes the tip (and
- *  cancels one still waiting). */
 export const focusOutMessage = (event: FocusEvent): Option.Option<Message> =>
   Option.map(
     Option.filter(
       tipTargetOf(event.target),
       ({ element }) =>
-        !(event.relatedTarget instanceof Node && element.contains(event.relatedTarget)),
+        !(
+          event.relatedTarget instanceof Node &&
+          element.contains(event.relatedTarget)
+        )
     ),
-    () => Message.BlurredTipTarget(),
+    () => Message.BlurredTipTarget()
   );
 
-/** A key pressed while a tip shows closes it and goes on its way. Escape on a tip that
- *  keyboard focus brought up closes the tip and nothing else: it is stopped before a menu or
- *  a dialog sees it. A pointer's tip lets Escape through, and a key that composes text (an
- *  input method) leaves the tip alone. */
-export const keyMessage = (event: KeyboardEvent, trigger: Trigger): Option.Option<Message> => {
+const isEscapeOnFocusTip = (event: KeyboardEvent, trigger: Trigger): boolean =>
+  event.key === "Escape" && trigger === "Focus";
+
+const keepFromMenusAndDialogs = (event: KeyboardEvent): void => {
+  event.preventDefault();
+  event.stopPropagation();
+};
+
+export const keyMessage = (
+  event: KeyboardEvent,
+  trigger: Trigger
+): Option.Option<Message> => {
   if (event.isComposing) {
     return Option.none();
   }
 
-  if (event.key === "Escape" && trigger === "Focus") {
-    event.preventDefault();
-    event.stopPropagation();
+  if (isEscapeOnFocusTip(event, trigger)) {
+    keepFromMenusAndDialogs(event);
   }
+
   return Option.some(Message.PressedKey());
 };
 
+const sameWords = (previous: Message, next: Message): boolean =>
+  previous._tag !== "EnteredTipTarget" ||
+  next._tag !== "EnteredTipTarget" ||
+  (previous.text === next.text &&
+    previous.side === next.side &&
+    Equal.equals(previous.maybeKey, next.maybeKey));
+
 const pointerOverChanges = (tipId: string): Stream.Stream<Message> =>
   Dom.streamFromEventFilterMap({
     target: document,
@@ -441,17 +499,11 @@ const pointerOverChanges = (tipId: string): Stream.Stream<Message> =>
     filterMapEvent: (event) => pointerOverMessage(tipId, event),
   }).pipe(
     Stream.changesWith(
-      (previous, next) => previous._tag === next._tag && sameWords(previous, next),
-    ),
+      (previous, next) =>
+        previous._tag === next._tag && sameWords(previous, next)
+    )
   );
 
-const sameWords = (previous: Message, next: Message): boolean =>
-  previous._tag !== "EnteredTipTarget" ||
-  next._tag !== "EnteredTipTarget" ||
-  (previous.text === next.text &&
-    previous.side === next.side &&
-    Equal.equals(previous.maybeKey, next.maybeKey));
-
 const tipSubscriptions = Subscription.make<Model, Message>()((entry) => ({
   pointerAndFocus: entry(
     { tipId: Schema.String },
@@ -477,14 +529,16 @@ const tipSubscriptions = Subscription.make<Model, Message>()((entry) => ({
               filterMapEvent: focusOutMessage,
             }),
           ],
-          { concurrency: "unbounded" },
+          { concurrency: "unbounded" }
         ),
-    },
+    }
   ),
   keys: entry(
     { maybeTrigger: Schema.Option(Trigger) },
     {
-      modelToDependencies: (model) => ({ maybeTrigger: maybeShownTrigger(model) }),
+      modelToDependencies: (model) => ({
+        maybeTrigger: maybeShownTrigger(model),
+      }),
       dependenciesToStream: ({ maybeTrigger }) =>
         Option.match(maybeTrigger, {
           onNone: () => Stream.empty,
@@ -496,7 +550,7 @@ const tipSubscriptions = Subscription.make<Model, Message>()((entry) => ({
               options: { capture: true },
             }),
         }),
-    },
+    }
   ),
 }));
 
@@ -507,13 +561,13 @@ const tipSubscriptions = Subscription.make<Model, Message>()((entry) => ({
 export const subscriptions = <Prefix extends string>(keyPrefix: Prefix) =>
   prefixKeys(keyPrefix, tipSubscriptions);
 
-// VIEW
-
 const maybeWordsOf = (model: Model): Option.Option<Words> =>
   Match.value(model.state).pipe(
     Match.withReturnType<Option.Option<Words>>(),
-    Match.tag("Waiting", "Shown", "Leaving", (words) => Option.some(wordsOf(words))),
-    Match.orElse(() => Option.none()),
+    Match.tag("Waiting", "Shown", "Leaving", (words) =>
+      Option.some(wordsOf(words))
+    ),
+    Match.orElse(() => Option.none())
   );
 
 /**
@@ -547,8 +601,10 @@ export const view = defineView<Model, Message>((model, h): Html => {
       onNone: () => [],
       onSome: ({ text, maybeKey }) => [
         text,
-        ...Array.fromOption(Option.map(maybeKey, (key) => h.kbd([h.Class("key-hint")], [key]))),
+        ...Array.fromOption(
+          Option.map(maybeKey, (key) => h.kbd([h.Class("key-hint")], [key]))
+        ),
       ],
-    }),
+    })
   );
 });

package/src/toast/index.ts

@@ -13,6 +13,9 @@ export {
   update,
   view,
 } from "./toast.ts";
+
 export type { InitConfig, ShowConfig } from "./toast.ts";
+
 export type { Action, Tone } from "./stack.ts";
+
 export { Focus } from "../focus/focus.ts";