@gjermundgaraba-designs/pixel-paper 0.26.0 → 0.27.0

package/src/menu/slip.ts

@@ -1,24 +1,29 @@
 import { Anchor, Button as UiButton } from "@foldkit/ui";
-import { Array, Effect, Match, Option, Queue, Schema, Stream, String, pipe } from "effect";
+import {
+  Array,
+  Effect,
+  Match,
+  Option,
+  Queue,
+  Schema,
+  Stream,
+  String,
+  pipe,
+} from "effect";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
 import type { Attributes } from "../attributes/attributes.ts";
 import type { KeyHintConfig } from "../button/button.ts";
+import { htmlElement } from "../dom/html-element.ts";
 import * as Glyph from "../glyph/glyph.ts";
 import type { GlyphName } from "../glyph/glyphs.ts";
-import * as KeyHint from "../keyHint/keyHint.ts";
+import * as KeyHint from "../key-hint/key-hint.ts";
 import { isPlain } from "../keys/keys.ts";
 import { Item } from "./item.ts";
 import type { Entry } from "./item.ts";
 
-// NOTE: the slip shared by Menu and ContextMenu: its rows, and the keys and focus rules of
-// the ARIA menu pattern. Each owner defines its own Mount over these helpers, so the
-// Messages are its own.
-
-// CHOICE
-
-/** What kind of row was chosen: a check keeps the slip open, the others close it. */
 export const ChoiceKind = Schema.Literals(["Action", "Radio", "Check", "Link"]);
+
 export type ChoiceKind = typeof ChoiceKind.Type;
 
 const ITEM_SELECTOR = '[role^="menuitem"]';
@@ -27,24 +32,22 @@ const LAST_ATTRIBUTE = "data-pixel-paper-slip-last";
 
 /** Where focus lands as the slip opens: its first row, or (↑ on the toggle) its last. */
 export const Edge = Schema.Literals(["First", "Last"]);
+
 export type Edge = typeof Edge.Type;
 
-/** The selector of the row focus lands on as the slip opens. */
 export const edgeSelector = (edge: Edge): string =>
   edge === "First" ? `[${FIRST_ATTRIBUTE}]` : `[${LAST_ATTRIBUTE}]`;
 
-// ROWS
-
 type Choosable = Exclude<Entry, Readonly<{ _tag: "Note" }>>;
 
 const isGroup = Item.$is("Group");
 
 const isNote = Item.$is("Note");
 
-const entriesOf = (items: ReadonlyArray<Item>): ReadonlyArray<Entry> =>
+const entriesOf = (items: readonly Item[]): readonly Entry[] =>
   Array.flatMap(items, (item) => (isGroup(item) ? item.items : [item]));
 
-const choosableIds = (items: ReadonlyArray<Item>): ReadonlyArray<string> =>
+const choosableIds = (items: readonly Item[]): readonly string[] =>
   Array.flatMap(entriesOf(items), (entry) => (isNote(entry) ? [] : [entry.id]));
 
 type RowContext<Message> = Readonly<{
@@ -56,10 +59,14 @@ type RowContext<Message> = Readonly<{
 const edgeAttributes = <Message>(
   context: RowContext<Message>,
   id: string,
-  h: HtmlBuilder<Message>,
+  h: HtmlBuilder<Message>
 ) => [
-  ...(Option.contains(context.firstId, id) ? [h.Attribute(FIRST_ATTRIBUTE, "")] : []),
-  ...(Option.contains(context.lastId, id) ? [h.Attribute(LAST_ATTRIBUTE, "")] : []),
+  ...(Option.contains(context.firstId, id)
+    ? [h.Attribute(FIRST_ATTRIBUTE, "")]
+    : []),
+  ...(Option.contains(context.lastId, id)
+    ? [h.Attribute(LAST_ATTRIBUTE, "")]
+    : []),
 ];
 
 const wordsView = <Message>(
@@ -68,25 +75,25 @@ const wordsView = <Message>(
     glyph?: GlyphName;
     keyHint?: KeyHintConfig;
   }>,
-  h: HtmlBuilder<Message>,
-): ReadonlyArray<Html> => [
+  h: HtmlBuilder<Message>
+): readonly Html[] => [
   ...(entry.glyph === undefined ? [] : [Glyph.view({ name: entry.glyph }, h)]),
   h.span([h.Class("menu-label")], [entry.label]),
   ...(entry.keyHint === undefined ? [] : [KeyHint.view(entry.keyHint, h)]),
 ];
 
-// a row that is a button: an action, a radio item or a check item
 const buttonRowView = <Message>(
   config: Readonly<{
     entry: Exclude<Choosable, Readonly<{ _tag: "Link" }>>;
     isDisabled: boolean;
     attributes: Attributes<Message>;
-    children: ReadonlyArray<Html>;
+    children: readonly Html[];
   }>,
   context: RowContext<Message>,
-  h: HtmlBuilder<Message>,
+  h: HtmlBuilder<Message>
 ): Html => {
   const { entry, isDisabled, attributes, children } = config;
+
   return UiButton.view(
     {
       onClick: context.toChoose(entry.id, entry._tag),
@@ -100,17 +107,17 @@ const buttonRowView = <Message>(
             h.Tabindex(-1),
             ...edgeAttributes(context, entry.id, h),
           ],
-          children,
+          children
         ),
     },
-    h,
+    h
   );
 };
 
 const choosableView = <Message>(
   entry: Choosable,
   context: RowContext<Message>,
-  h: HtmlBuilder<Message>,
+  h: HtmlBuilder<Message>
 ): Html =>
   Match.value(entry).pipe(
     Match.withReturnType<Html>(),
@@ -123,8 +130,8 @@ const choosableView = <Message>(
           children: wordsView(action, h),
         },
         context,
-        h,
-      ),
+        h
+      )
     ),
     Match.tag("Radio", (radio) =>
       buttonRowView(
@@ -135,23 +142,26 @@ const choosableView = <Message>(
           children: wordsView(radio, h),
         },
         context,
-        h,
-      ),
+        h
+      )
     ),
     Match.tag("Check", (check) =>
       buttonRowView(
         {
           entry: check,
           isDisabled: false,
-          attributes: [h.Role("menuitemcheckbox"), h.AriaChecked(check.isChecked)],
+          attributes: [
+            h.Role("menuitemcheckbox"),
+            h.AriaChecked(check.isChecked),
+          ],
           children: [
             h.span([h.Class("menu-check"), h.AriaHidden(true)]),
             h.span([h.Class("menu-label")], [check.label]),
           ],
         },
         context,
-        h,
-      ),
+        h
+      )
     ),
     Match.tag("Link", (link) =>
       h.keyed("a")(
@@ -164,32 +174,31 @@ const choosableView = <Message>(
           h.OnClick(context.toChoose(link.id, link._tag)),
           ...edgeAttributes(context, link.id, h),
         ],
-        wordsView(link, h),
-      ),
+        wordsView(link, h)
+      )
     ),
-    Match.exhaustive,
+    Match.exhaustive
   );
 
 const entryView = <Message>(
   entry: Entry,
   context: RowContext<Message>,
-  h: HtmlBuilder<Message>,
+  h: HtmlBuilder<Message>
 ): Html =>
   isNote(entry)
     ? h.span([h.Class("menu-note"), h.Role("none")], [entry.text])
     : choosableView(entry, context, h);
 
-/** The slip's rows: items, groups under their headings, and notes. `slipId` names the group
- *  headings' ids; `toChoose` is the Message a row's click sends. */
 export const rowsView = <Message>(
   config: Readonly<{
     slipId: string;
-    items: ReadonlyArray<Item>;
+    items: readonly Item[];
     toChoose: (id: string, kind: ChoiceKind) => Message;
   }>,
-  h: HtmlBuilder<Message>,
-): ReadonlyArray<Html> => {
+  h: HtmlBuilder<Message>
+): readonly Html[] => {
   const ids = choosableIds(config.items);
+
   const context: RowContext<Message> = {
     firstId: Array.head(ids),
     lastId: Array.last(ids),
@@ -200,106 +209,124 @@ export const rowsView = <Message>(
     if (!isGroup(item)) {
       return entryView(item, context, h);
     }
+
     const headingId = `${config.slipId}-group-${index}`;
+
     return h.keyed("div")(
       `group:${item.label}`,
       [h.Role("group"), h.AriaLabelledBy(headingId)],
       [
-        h.span([h.Id(headingId), h.Class("menu-note"), h.Role("none")], [item.label]),
+        h.span(
+          [h.Id(headingId), h.Class("menu-note"), h.Role("none")],
+          [item.label]
+        ),
         ...Array.map(item.items, (entry) => entryView(entry, context, h)),
-      ],
+      ]
     );
   });
 };
 
-// KEYS
-
-/** The Messages a slip's keys and focus report to its owner. */
 type SlipEvents<Message> = Readonly<{
-  /** Escape: close and put focus back. Its default is prevented, so a Dialog the slip sits
-   *  in stays open. */
   escape: Message;
-  /** Tab: close and put focus back where the slip came from. */
   tab: Message;
-  /** Focus went somewhere outside the slip (a click elsewhere): close and leave it there. */
   left: Message;
 }>;
 
-const itemsOf = (slip: Element): ReadonlyArray<HTMLElement> =>
+const itemsOf = (slip: Element): readonly HTMLElement[] =>
   Array.fromIterable(slip.querySelectorAll<HTMLElement>(ITEM_SELECTOR));
 
-const focusedIndex = (items: ReadonlyArray<HTMLElement>): Option.Option<number> =>
+const focusedIndex = (items: readonly HTMLElement[]): Option.Option<number> =>
   Array.findFirstIndex(items, (item) => item === document.activeElement);
 
-const focusAt = (items: ReadonlyArray<HTMLElement>, index: number): boolean =>
+const focusAt = (items: readonly HTMLElement[], index: number): boolean =>
   Option.match(Array.get(items, index), {
     onNone: () => false,
     onSome: (item) => {
       item.focus();
+
       return true;
     },
   });
 
-const wrap = (index: number, length: number): number => (index + length) % length;
+const wrap = (index: number, length: number): number =>
+  (index + length) % length;
 
 const startsWith = (item: HTMLElement, key: string): boolean =>
   pipe(
     item.textContent ?? "",
     String.trim,
     String.toLowerCase,
-    String.startsWith(String.toLowerCase(key)),
+    String.startsWith(String.toLowerCase(key))
   );
 
-const typeahead = (items: ReadonlyArray<HTMLElement>, key: string): boolean => {
+const typeahead = (items: readonly HTMLElement[], key: string): boolean => {
   const from = Option.getOrElse(focusedIndex(items), () => -1);
-  const ordered = [...Array.drop(items, from + 1), ...Array.take(items, from + 1)];
+
+  const ordered = [
+    ...Array.drop(items, from + 1),
+    ...Array.take(items, from + 1),
+  ];
+
   return Option.match(
     Array.findFirst(ordered, (item) => startsWith(item, key)),
     {
       onNone: () => false,
       onSome: (item) => {
         item.focus();
+
         return true;
       },
-    },
+    }
   );
 };
 
-// Shift+Tab leaves the slip backwards as Tab leaves it forwards, so Tab alone takes Shift.
 const isShiftTab = (event: KeyboardEvent): boolean =>
-  event.key === "Tab" && event.shiftKey && !event.altKey && !event.ctrlKey && !event.metaKey;
+  event.key === "Tab" &&
+  event.shiftKey &&
+  !event.altKey &&
+  !event.ctrlKey &&
+  !event.metaKey;
 
-/** What one keydown in the slip does: ↑ and ↓ move focus among its rows and wrap, Home and End
- *  go to the ends, a letter goes to the next row it starts, Escape and Tab (or Shift+Tab)
- *  report. Unavailable rows are stopped on too. Returns whether it acted, and prevents the
- *  default when it did. */
 const handleSlipKey = <Message>(
   slip: Element,
   event: KeyboardEvent,
-  events: SlipEvents<Message>,
+  events: SlipEvents<Message>
 ): Option.Option<Message> => {
-  if (event.isComposing || event.defaultPrevented || !(isPlain(event) || isShiftTab(event))) {
+  if (
+    event.isComposing ||
+    event.defaultPrevented ||
+    !(isPlain(event) || isShiftTab(event))
+  ) {
     return Option.none();
   }
+
   const items = itemsOf(slip);
-  const length = items.length;
+  const { length } = items;
   const current = Option.getOrElse(focusedIndex(items), () => -1);
+
   const moved = (didMove: boolean): Option.Option<Message> => {
     if (didMove) {
       event.preventDefault();
     }
+
     return Option.none();
   };
+
   const reported = (message: Message): Option.Option<Message> => {
     event.preventDefault();
+
     return Option.some(message);
   };
 
   return Match.value(event.key).pipe(
     Match.withReturnType<Option.Option<Message>>(),
-    Match.when("ArrowDown", () => moved(length > 0 && focusAt(items, wrap(current + 1, length)))),
+    Match.when("ArrowDown", () =>
+      moved(length > 0 && focusAt(items, wrap(current + 1, length)))
+    ),
     Match.when("ArrowUp", () =>
-      moved(length > 0 && focusAt(items, wrap(Math.max(current, 0) - 1, length))),
+      moved(
+        length > 0 && focusAt(items, wrap(Math.max(current, 0) - 1, length))
+      )
     ),
     Match.when("Home", () => moved(focusAt(items, 0))),
     Match.when("End", () => moved(focusAt(items, length - 1))),
@@ -307,45 +334,54 @@ const handleSlipKey = <Message>(
     Match.when("Tab", () => reported(events.tab)),
     Match.when(
       (key) => key.length === 1 && key !== " ",
-      (key) => moved(typeahead(items, key)),
+      (key) => moved(typeahead(items, key))
     ),
-    Match.orElse(() => Option.none()),
+    Match.orElse(() => Option.none())
   );
 };
 
-/** Whether focus leaving the slip for `next` closes it: anything but the slip itself and the
- *  element whose id is `keepId` (the toggle, which closes it on its own click). */
-const isLeaving = (slip: Element, next: EventTarget | null, keepId: Option.Option<string>) =>
+const isLeaving = (
+  slip: Element,
+  next: EventTarget | null,
+  keepId: Option.Option<string>
+) =>
   !(next instanceof Node && slip.contains(next)) &&
   !(next instanceof Element && Option.contains(keepId, next.id));
 
+const preventMouseDown = (event: Event): void => {
+  event.preventDefault();
+};
+
 /** The slip's keys and focus as a stream of its owner's Messages, set up by `setup` (anchoring,
  *  portaling) and torn down with the element. A press inside the slip keeps focus where it
  *  is, so a click on a row reaches it in every browser. */
 export const slipStream = <Message>(
   element: Element,
   config: Readonly<{
-    /** Reported once the slip is placed and its keys are bound. */
     placed: Message;
     events: SlipEvents<Message>;
     keepId: Option.Option<string>;
     setup: (element: Element) => () => void;
-  }>,
+  }>
 ): Stream.Stream<Message> =>
   Stream.callback<Message>((queue) =>
     Effect.gen(function* () {
       yield* Effect.acquireRelease(
         Effect.sync(() => {
           const cleanup = config.setup(element);
+
           const onKeyDown = (event: Event): void => {
             if (!(event instanceof KeyboardEvent)) {
               return;
             }
+
             const maybeMessage = handleSlipKey(element, event, config.events);
+
             if (Option.isSome(maybeMessage)) {
               Queue.offerUnsafe(queue, maybeMessage.value);
             }
           };
+
           const onFocusOut = (event: Event): void => {
             if (
               event instanceof FocusEvent &&
@@ -354,31 +390,29 @@ export const slipStream = <Message>(
               Queue.offerUnsafe(queue, config.events.left);
             }
           };
-          const onMouseDown = (event: Event): void => event.preventDefault();
+
           element.addEventListener("keydown", onKeyDown);
           element.addEventListener("focusout", onFocusOut);
-          element.addEventListener("mousedown", onMouseDown);
+          element.addEventListener("mousedown", preventMouseDown);
+
           return () => {
             element.removeEventListener("keydown", onKeyDown);
             element.removeEventListener("focusout", onFocusOut);
-            element.removeEventListener("mousedown", onMouseDown);
+            element.removeEventListener("mousedown", preventMouseDown);
             cleanup();
           };
         }),
-        (teardown) => Effect.sync(teardown),
+        (teardown) => Effect.sync(teardown)
       );
       Queue.offerUnsafe(queue, config.placed);
+
       return yield* Effect.never;
-    }),
+    })
   );
 
-// PLACEMENT
-
 const GAP = 6;
 const WINDOW_PADDING = 12;
 
-/** Hangs the slip under its toggle with `@foldkit/ui`'s Anchor (portaled out of clipping
- *  ancestors, into the dialog when inside one), then focuses the row at `edge`. */
 export const anchorUnder =
   (config: Readonly<{ toggleId: string; isEnd: boolean; edge: Edge }>) =>
   (element: Element): (() => void) =>
@@ -395,30 +429,33 @@ export const anchorUnder =
     });
 
 /** Where a context slip opens, in viewport pixels. */
-export const Point = Schema.Struct({ x: Schema.Number, y: Schema.Number });
+export const Point = Schema.Struct({ x: Schema.Finite, y: Schema.Finite });
+
 export type Point = typeof Point.Type;
 
 const clampInto = (start: number, size: number, limit: number): number =>
-  start + size > limit - WINDOW_PADDING ? Math.max(WINDOW_PADDING, start - size) : start;
+  start + size > limit - WINDOW_PADDING
+    ? Math.max(WINDOW_PADDING, start - size)
+    : start;
 
-/** Opens the slip at a point, portaled, kept 12px inside the window (flipping to the other
- *  side of the point when it would cross the edge), then focuses its first row. */
 export const placeAt =
   (point: Point) =>
   (element: Element): (() => void) => {
     const cleanup = Anchor.portalToContainingRoot(element);
+
     if (element instanceof HTMLElement) {
       element.style.left = `${point.x}px`;
       element.style.top = `${point.y}px`;
       const rect = element.getBoundingClientRect();
       element.style.left = `${clampInto(point.x, rect.width, window.innerWidth)}px`;
       element.style.top = `${clampInto(point.y, rect.height, window.innerHeight)}px`;
-      const maybeFirst = Option.fromNullishOr(
-        element.querySelector<HTMLElement>(edgeSelector("First")),
-      );
+
+      const maybeFirst = htmlElement(edgeSelector("First"), element);
+
       if (Option.isSome(maybeFirst)) {
         maybeFirst.value.focus({ preventScroll: true });
       }
     }
+
     return cleanup;
   };

package/src/meter/index.ts

@@ -1,2 +1,3 @@
 export { cellsView, listView } from "./meter.ts";
+
 export type { CellsConfig, ListViewConfig, MeterConfig } from "./meter.ts";