@gjermundgaraba-designs/pixel-paper 0.26.0 → 0.27.0

package/src/menu/index.ts

@@ -11,7 +11,11 @@ export {
   update,
   view,
 } from "./menu.ts";
+
 export type { Align, InitConfig, ViewInputs } from "./menu.ts";
+
 export { action, check, group, link, note, radio } from "./item.ts";
+
 export type { Item } from "./item.ts";
+
 export { Focus } from "../focus/focus.ts";

package/src/menu/item.ts

@@ -3,11 +3,6 @@ import { Data } from "effect";
 import type { KeyHintConfig } from "../button/button.ts";
 import type { GlyphName } from "../glyph/glyphs.ts";
 
-// ITEM
-
-// NOTE: a tagged enum, not a Schema union: an item carries a `KeyHintConfig`, which has no
-// Schema, and items live in view inputs, never in a Model.
-
 /** One entry in a menu. Build them with `action`, `radio`, `check`, `link`, `note` and
  *  `group`. */
 export type Item = Data.TaggedEnum<{
@@ -57,7 +52,7 @@ export type Item = Data.TaggedEnum<{
   /** Items under a heading (`role="group"`, named by the heading): `"Appearance"` over the
    *  palettes, `"Account"` over sign out. A set of radio items belongs in one. The label is
    *  the group's identity in its slip: two groups there do not share one. */
-  Group: { readonly label: string; readonly items: ReadonlyArray<Entry> };
+  Group: { readonly label: string; readonly items: readonly Entry[] };
 }>;
 
 /** One row of a menu or of a group: any item but a group. */
@@ -67,20 +62,24 @@ export type Entry = Exclude<Item, { readonly _tag: "Group" }>;
 export const Item = Data.taggedEnum<Item>();
 
 /** An action item; see `Item`'s `Action`. */
-export const action = (config: Data.TaggedEnum.Args<Item, "Action">): Entry => Item.Action(config);
+export const action = (config: Data.TaggedEnum.Args<Item, "Action">): Entry =>
+  Item.Action(config);
 
 /** A radio item; see `Item`'s `Radio`. */
-export const radio = (config: Data.TaggedEnum.Args<Item, "Radio">): Entry => Item.Radio(config);
+export const radio = (config: Data.TaggedEnum.Args<Item, "Radio">): Entry =>
+  Item.Radio(config);
 
 /** A check item; see `Item`'s `Check`. */
-export const check = (config: Data.TaggedEnum.Args<Item, "Check">): Entry => Item.Check(config);
+export const check = (config: Data.TaggedEnum.Args<Item, "Check">): Entry =>
+  Item.Check(config);
 
 /** A link item; see `Item`'s `Link`. */
-export const link = (config: Data.TaggedEnum.Args<Item, "Link">): Entry => Item.Link(config);
+export const link = (config: Data.TaggedEnum.Args<Item, "Link">): Entry =>
+  Item.Link(config);
 
 /** A note; see `Item`'s `Note`. */
 export const note = (text: string): Entry => Item.Note({ text });
 
 /** A group of items under a heading; see `Item`'s `Group`. */
-export const group = (label: string, items: ReadonlyArray<Entry>): Item =>
+export const group = (label: string, items: readonly Entry[]): Item =>
   Item.Group({ label, items });

package/src/menu/menu.ts

@@ -16,15 +16,14 @@ import * as Glyph from "../glyph/glyph.ts";
 import type { GlyphName } from "../glyph/glyphs.ts";
 import { isPlain } from "../keys/keys.ts";
 import type { Item } from "./item.ts";
-import { ChoiceKind, Edge, anchorUnder, edgeSelector, rowsView, slipStream } from "./slip.ts";
-
-// NOTE: @foldkit/ui gap: Menu's rows are always `role="menuitem"` with no hook for a row's
-// role or attributes (no `menuitemradio`, `menuitemcheckbox` or `aria-checked`), its arrows
-// pass unavailable rows (the ARIA menu pattern stops on them), and its row ids are private.
-// So this menu is not built on it: it follows the ARIA menu pattern with real focus on its
-// rows, positioned by `@foldkit/ui`'s public Anchor.
-
-// MODEL
+import {
+  ChoiceKind,
+  Edge,
+  anchorUnder,
+  edgeSelector,
+  rowsView,
+  slipStream,
+} from "./slip.ts";
 
 /** Schema for a menu: its id, whether its slip is open, and which end of the slip takes
  *  focus as it opens. One Model serves one toggle: a menu on every row of a list is a Model
@@ -34,9 +33,8 @@ export const Model = Schema.Struct({
   isOpen: Schema.Boolean,
   edge: Edge,
 });
-export type Model = typeof Model.Type;
 
-// MESSAGE
+export type Model = typeof Model.Type;
 
 /** Union of all Messages a menu can produce. `LeftSlip` (focus went outside the slip),
  *  `UnmountedSlip` (the slip left the page) and `CompletedFocus` (focus is back on the
@@ -55,9 +53,8 @@ export const Message = defineMessageUnion({
   CompletedFocus: {},
   CompletedFocusEdge: {},
 });
-export type Message = typeof Message.Type;
 
-// OUT MESSAGE
+export type Message = typeof Message.Type;
 
 /** Union of OutMessages a menu reports. `Selected`: an action, a radio item or a link was
  *  chosen and the slip has closed (the browser follows a link itself). `Toggled`: a check item
@@ -66,9 +63,8 @@ export const OutMessage = defineMessageUnion({
   Selected: { id: Schema.String },
   Toggled: { id: Schema.String },
 });
-export type OutMessage = typeof OutMessage.Type;
 
-// INIT
+export type OutMessage = typeof OutMessage.Type;
 
 /** Configuration for creating a menu with `init`. The `id` must be unique in the document. */
 export type InitConfig = Readonly<{ id: string }>;
@@ -80,8 +76,6 @@ export const init = (config: InitConfig): Model => ({
   edge: "First",
 });
 
-// ACCESSORS
-
 /** The menu's id, unique in the document. */
 export const id = (model: Model): string => model.id;
 
@@ -92,25 +86,23 @@ const toggleId = (model: Model): string => `${model.id}-toggle`;
 
 const slipId = (model: Model): string => `${model.id}-slip`;
 
-// UPDATE
-
 /** Moves focus to an end of the open slip (↓ or ↑ on the toggle while it is open). */
 export const FocusEdge = Command.define("FocusEdge", {
   args: { slipId: Schema.String, edge: Edge },
   messages: [Message.CompletedFocusEdge],
-  execute: ({ slipId: id, edge }) =>
-    Dom.focus(`#${CSS.escape(id)} ${edgeSelector(edge)}`).pipe(
+  execute: ({ slipId: openSlipId, edge }) =>
+    Dom.focus(`#${CSS.escape(openSlipId)} ${edgeSelector(edge)}`).pipe(
       Effect.ignore,
-      Effect.as(Message.CompletedFocusEdge()),
+      Effect.as(Message.CompletedFocusEdge())
     ),
 });
 
 const opened = (model: Model, edge: Edge): Model =>
   modifyFields(model, { isOpen: () => true, edge: () => edge });
 
-const closed = (model: Model): Model => modifyFields(model, { isOpen: () => false });
+const closed = (model: Model): Model =>
+  modifyFields(model, { isOpen: () => false });
 
-// focus goes back on the toggle as the slip closes by Escape, Tab or a choice
 const closedWithFocus = (model: Model): Update.Return<Model, Message> => ({
   model: closed(model),
   commands: [Focus({ id: toggleId(model) })],
@@ -118,44 +110,49 @@ const closedWithFocus = (model: Model): Update.Return<Model, Message> => ({
 
 /** Processes a menu Message and returns the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message) =>
-  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(message, {
-    ClickedToggle: () => ({ model: model.isOpen ? closed(model) : opened(model, "First") }),
-    PressedToggleArrow: ({ edge }) =>
-      model.isOpen
-        ? { model, commands: [FocusEdge({ slipId: slipId(model), edge })] }
-        : { model: opened(model, edge) },
-    SelectedItem: ({ id: itemId, kind }) =>
-      kind === "Check"
-        ? { model, outMessage: OutMessage.Toggled({ id: itemId }) }
-        : pipe(closedWithFocus(model), Update.withOutMessage(OutMessage.Selected({ id: itemId }))),
-    PressedEscape: () => closedWithFocus(model),
-    PressedTab: () => closedWithFocus(model),
-    LeftSlip: () => ({ model: closed(model) }),
-    UnmountedSlip: () => ({ model: closed(model) }),
-    CompletedPlaceSlip: () => ({ model }),
-    CompletedFocus: () => ({ model }),
-    CompletedFocusEdge: () => ({ model }),
-  });
-
-// KEYS
+  Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(
+    message,
+    {
+      ClickedToggle: () => ({
+        model: model.isOpen ? closed(model) : opened(model, "First"),
+      }),
+      PressedToggleArrow: ({ edge }) =>
+        model.isOpen
+          ? { model, commands: [FocusEdge({ slipId: slipId(model), edge })] }
+          : { model: opened(model, edge) },
+      SelectedItem: ({ id: itemId, kind }) =>
+        kind === "Check"
+          ? { model, outMessage: OutMessage.Toggled({ id: itemId }) }
+          : pipe(
+              closedWithFocus(model),
+              Update.withOutMessage(OutMessage.Selected({ id: itemId }))
+            ),
+      PressedEscape: () => closedWithFocus(model),
+      PressedTab: () => closedWithFocus(model),
+      LeftSlip: () => ({ model: closed(model) }),
+      UnmountedSlip: () => ({ model: closed(model) }),
+      CompletedPlaceSlip: () => ({ model }),
+      CompletedFocus: () => ({ model }),
+      CompletedFocusEdge: () => ({ model }),
+    }
+  );
 
 const toggleEdge = (key: string): Option.Option<Edge> =>
   Match.value(key).pipe(
     Match.withReturnType<Option.Option<Edge>>(),
     Match.when("ArrowDown", () => Option.some("First")),
     Match.when("ArrowUp", () => Option.some("Last")),
-    Match.orElse(() => Option.none()),
+    Match.orElse(() => Option.none())
   );
 
-/** What one keydown on the toggle does: ↓ and ↑ open the slip on its first or last row. A
- *  key an IME is composing, a modified key, a key someone already handled and any other key
- *  are left alone. */
 export const toggleKey = (
-  event: KeyboardEvent,
+  event: KeyboardEvent
 ): Option.Option<typeof Message.PressedToggleArrow.Type> =>
   event.isComposing || event.defaultPrevented || !isPlain(event)
     ? Option.none()
-    : Option.map(toggleEdge(event.key), (edge) => Message.PressedToggleArrow({ edge }));
+    : Option.map(toggleEdge(event.key), (edge) =>
+        Message.PressedToggleArrow({ edge })
+      );
 
 /** ↓ and ↑ on the toggle open the slip on its first or last row (Enter and Space click it),
  *  their default prevented (see `toggleKey`). In a Scene, resolve it with
@@ -187,7 +184,7 @@ export const BindSlip = Mount.defineStream("BindSlip", {
     Message.PressedTab,
     Message.LeftSlip,
   ],
-  execute: ({ element, toggleId: id, isEnd, edge }) =>
+  execute: ({ element, toggleId: slipToggleId, isEnd, edge }) =>
     slipStream<SlipMessage>(element, {
       placed: Message.CompletedPlaceSlip(),
       events: {
@@ -195,15 +192,14 @@ export const BindSlip = Mount.defineStream("BindSlip", {
         tab: Message.PressedTab(),
         left: Message.LeftSlip(),
       },
-      keepId: Option.some(id),
-      setup: anchorUnder({ toggleId: id, isEnd, edge }),
+      keepId: Option.some(slipToggleId),
+      setup: anchorUnder({ toggleId: slipToggleId, isEnd, edge }),
     }),
 });
 
-// VIEW
-
 /** Which edge of the toggle the slip hangs from. */
 export const Align = Schema.Literals(["Start", "End"]);
+
 export type Align = typeof Align.Type;
 
 /** Per-render inputs passed to `view` through `h.submodel`'s `viewInputs`. */
@@ -212,7 +208,7 @@ export type ViewInputs = Readonly<{
    *  `glyph` or `toggleContent` replaces them; then it is the toggle's `aria-label` and tip,
    *  so start it with any words the content shows. */
   label: string;
-  items: ReadonlyArray<Item>;
+  items: readonly Item[];
   /** A glyph toggle (`iconbtn`): the glyph alone, `label` its name and tip. */
   glyph?: GlyphName;
   /** A glyph toggle muted until hovered: a row's `more` menu. */
@@ -227,19 +223,29 @@ export type ViewInputs = Readonly<{
   align?: Align;
 }>;
 
-// a toggle that shows a glyph or its own content says its label as its name and tip
 const isNamedByLabel = (viewInputs: ViewInputs): boolean =>
   viewInputs.glyph !== undefined || viewInputs.toggleContent !== undefined;
 
 const toggleClass = (viewInputs: ViewInputs): string => {
-  const { glyph, isQuiet = false, toggleContent, variant = "Default" } = viewInputs;
+  const {
+    glyph,
+    isQuiet = false,
+    toggleContent,
+    variant = "Default",
+  } = viewInputs;
+
   if (glyph === undefined || toggleContent !== undefined) {
     return lookClassName({ variant, isSmall: true });
   }
+
   return isQuiet ? "iconbtn quiet" : "iconbtn";
 };
 
-const toggleView = (model: Model, viewInputs: ViewInputs, h: HtmlBuilder<Message>): Html => {
+const toggleView = (
+  model: Model,
+  viewInputs: ViewInputs,
+  h: HtmlBuilder<Message>
+): Html => {
   const { label, glyph, toggleContent } = viewInputs;
 
   return UiButton.view(
@@ -259,10 +265,11 @@ const toggleView = (model: Model, viewInputs: ViewInputs, h: HtmlBuilder<Message
             h.OnMount(BindToggleKeys()),
             h.Class(toggleClass(viewInputs)),
           ],
-          toggleContent ?? (glyph === undefined ? [label] : [Glyph.view({ name: glyph }, h)]),
+          toggleContent ??
+            (glyph === undefined ? [label] : [Glyph.view({ name: glyph }, h)])
         ),
     },
-    h,
+    h
   );
 };
 
@@ -279,40 +286,46 @@ const toggleView = (model: Model, viewInputs: ViewInputs, h: HtmlBuilder<Message
  * `aria-current`. A check row keeps the slip open. The menu does not trap focus, so it
  * hosts no live region.
  */
-export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { label, items, align = "Start" } = viewInputs;
-
-  return h.div(
-    [h.Class("menu-wrap")],
-    [
-      toggleView(model, viewInputs, h),
-      ...(model.isOpen
-        ? [
-            h.div(
-              [
-                h.Id(slipId(model)),
-                h.Role("menu"),
-                isNamedByLabel(viewInputs) ? h.AriaLabel(label) : h.AriaLabelledBy(toggleId(model)),
-                h.OnMount(
-                  BindSlip({ toggleId: toggleId(model), isEnd: align === "End", edge: model.edge }),
-                ),
-                // NOTE: the slip's Mount ends after the patch that removes it, too late to
-                // report, so a slip that leaves the page with its toggle (the row it sits on
-                // is gone) says so here, and the menu closes.
-                h.OnUnmount(Message.UnmountedSlip()),
-                h.Class("menu"),
-              ],
-              rowsView(
-                {
-                  slipId: slipId(model),
-                  items,
-                  toChoose: (itemId, kind) => Message.SelectedItem({ id: itemId, kind }),
-                },
-                h,
+export const view = defineView<Model, Message, ViewInputs>(
+  (model, viewInputs, h): Html => {
+    const { label, items, align = "Start" } = viewInputs;
+
+    return h.div(
+      [h.Class("menu-wrap")],
+      [
+        toggleView(model, viewInputs, h),
+        ...(model.isOpen
+          ? [
+              h.div(
+                [
+                  h.Id(slipId(model)),
+                  h.Role("menu"),
+                  isNamedByLabel(viewInputs)
+                    ? h.AriaLabel(label)
+                    : h.AriaLabelledBy(toggleId(model)),
+                  h.OnMount(
+                    BindSlip({
+                      toggleId: toggleId(model),
+                      isEnd: align === "End",
+                      edge: model.edge,
+                    })
+                  ),
+                  h.OnUnmount(Message.UnmountedSlip()),
+                  h.Class("menu"),
+                ],
+                rowsView(
+                  {
+                    slipId: slipId(model),
+                    items,
+                    toChoose: (itemId, kind) =>
+                      Message.SelectedItem({ id: itemId, kind }),
+                  },
+                  h
+                )
               ),
-            ),
-          ]
-        : []),
-    ],
-  );
-});
+            ]
+          : []),
+      ]
+    );
+  }
+);