@gjermundgaraba-designs/pixel-paper 0.22.2 → 0.24.0

package/src/rail/index.ts

@@ -1,4 +1,5 @@
 export {
+  FocusRailToggle,
   FollowRailDrawer,
   HideRailDrawer,
   Message,
@@ -10,6 +11,7 @@ export {
   init,
   isOpen,
   subscriptions,
+  toggle,
   update,
   view,
 } from "./rail.ts";

package/src/rail/rail.ts

@@ -27,8 +27,8 @@ const Resizing = Schema.Struct({
 });
 
 /** Schema for a rail: whether it is open as a drawer (at 900px and under; wider, it is always
- *  in the page and this stays false), and its splitter while a pointer drags it. Its width is
- *  the parent's. */
+ *  in the page and this stays false), and its splitter while a pointer drags it. Its width,
+ *  and whether the reader hid it, are the parent's. */
 export const Model = Schema.Struct({
   id: Schema.String,
   isOpen: Schema.Boolean,
@@ -43,6 +43,7 @@ export type Model = typeof Model.Type;
  *  the window growing past 900px while it is open, where the rail is back in the page. */
 export const Message = defineMessageUnion({
   ClickedOpen: {},
+  ClickedToggle: {},
   PressedSplitter: { pointerId: Schema.Number, clientX: Schema.Number, width: Schema.Number },
   MovedSplitter: { clientX: Schema.Number },
   ReleasedSplitter: { clientX: Schema.Number },
@@ -55,14 +56,18 @@ export const Message = defineMessageUnion({
   WidenedPastDrawer: {},
   CompletedShowRailDrawer: {},
   CompletedHideRailDrawer: {},
+  CompletedFocusRailToggle: {},
 });
 export type Message = typeof Message.Type;
 
 /** What a rail asks of its parent. `ResizedRail`: its splitter was let go, or stepped by a
  *  key, at `width` pixels, within the rail's bounds; the parent keeps it (per client) and
- *  passes it back as the view's `maybeWidth`. */
+ *  passes it back as the view's `maybeWidth`. `ToggledRail`: its toggle was pressed; the
+ *  parent flips whether it keeps the rail hidden (per client) and passes it back as the view's
+ *  `isHidden`. */
 export const OutMessage = defineMessageUnion({
   ResizedRail: { width: Schema.Number },
+  ToggledRail: {},
 });
 export type OutMessage = typeof OutMessage.Type;
 
@@ -87,7 +92,7 @@ export const init = (config: InitConfig): Model => ({
  *  (which leaves the deck at least 421px of a 901px window, the narrowest one the rail stands
  *  in, more than a phone has), and what an arrow on its splitter moves it. The bounds and the
  *  step are the component's, not tokens: the splitter says them as its values. */
-const WIDTH = { start: 272, least: 220, most: 480, step: 16 };
+export const WIDTH = { start: 272, least: 220, most: 480, step: 16 };
 
 const bounded = (width: number): number =>
   Math.round(Number.clamp(width, { minimum: WIDTH.least, maximum: WIDTH.most }));
@@ -102,6 +107,8 @@ export const isOpen = (model: Model): boolean => model.isOpen;
 
 const openButtonId = (model: Model): string => `${model.id}-open`;
 
+const toggleId = (model: Model): string => `${model.id}-toggle`;
+
 // COMMAND
 
 const FOCUSABLE =
@@ -113,11 +120,13 @@ const findRail = (railId: string): Effect.Effect<HTMLElement, Cause.NoSuchElemen
   );
 
 /** The drawer's first Tab stop past its head: a control the keyboard reaches, so a tree's
- *  items other than its one stop (`tabindex="-1"`) are passed over. */
+ *  items other than its one stop (`tabindex="-1"`) are passed over, and so is the toggle,
+ *  which the drawer does not print. */
 export const firstTabStop = (rail: Element): Option.Option<HTMLElement> =>
   Array.findFirst(
     Array.fromIterable(rail.querySelectorAll<HTMLElement>(`.rail-head ~ * :is(${FOCUSABLE})`)),
-    (control) => control.tabIndex >= 0 && control.closest("[inert], [hidden]") === null,
+    (control) =>
+      control.tabIndex >= 0 && control.closest("[inert], [hidden], .rail-toggle") === null,
   );
 
 /** Opens the rail as a drawer over the page and puts focus on its first control past its
@@ -157,6 +166,25 @@ export const HideRailDrawer = Command.define("HideRailDrawer", {
     ),
 });
 
+/** Puts focus on the rail's toggle once the rail has folded or unfolded, if focus was in the
+ *  rail or on its splitter: folding takes away every control in it but the toggle, which
+ *  brings it back, and the splitter with them. Focus anywhere else stays where it is. */
+export const FocusRailToggle = Command.define("FocusRailToggle", {
+  args: { railId: Schema.String, toggleId: Schema.String },
+  messages: [Message.CompletedFocusRailToggle],
+  execute: ({ railId, toggleId: buttonId }) =>
+    Effect.gen(function* () {
+      // NOTE: read before the fold renders, which takes away the control focus is on
+      const rail = yield* findRail(railId);
+      const active = document.activeElement;
+      const isOnSplitter =
+        active?.matches(`.rail-resize[aria-controls="${CSS.escape(railId)}"]`) ?? false;
+      if (rail.contains(active) || isOnSplitter) {
+        yield* Dom.focus(`#${CSS.escape(buttonId)}`);
+      }
+    }).pipe(Effect.ignore, Effect.as(Message.CompletedFocusRailToggle())),
+});
+
 // UPDATE
 
 type UpdateReturn = Update.Return<Model, Message>;
@@ -180,6 +208,14 @@ const open = (model: Model): UpdateReturn => ({
 /** Closes the rail's drawer, focus back on its button. */
 export const close = (model: Model): UpdateReturn => closeDrawer(model, true);
 
+/** Folds or unfolds the rail from a key of the parent's: the parent flips whether it keeps the
+ *  rail hidden, as it does for `ToggledRail`, and folds this in, which moves focus in the rail
+ *  onto the toggle. */
+export const toggle = (model: Model): UpdateReturn => ({
+  model,
+  commands: [FocusRailToggle({ railId: model.id, toggleId: toggleId(model) })],
+});
+
 const withResizing = (model: Model, maybeResizing: Option.Option<typeof Resizing.Type>): Model =>
   modifyFields(model, { maybeResizing: () => maybeResizing });
 
@@ -194,10 +230,12 @@ const dragTo = (model: Model, clientX: number): Model =>
   );
 
 /** Processes a rail Message and returns the next Model, Commands and OutMessage: a splitter let
- *  go where it changes the width, or stepped by a key, asks for the width. */
+ *  go where it changes the width, or stepped by a key, asks for the width, and the toggle asks
+ *  to fold or unfold the rail. */
 export const update = (model: Model, message: Message) =>
   Message.match<Update.ReturnWithOutMessage<Model, Message, OutMessage>>(message, {
     ClickedOpen: () => open(model),
+    ClickedToggle: () => ({ ...toggle(model), outMessage: OutMessage.ToggledRail() }),
     PressedSplitter: ({ pointerId, clientX, width }) =>
       Option.isSome(model.maybeResizing)
         ? { model }
@@ -228,6 +266,7 @@ export const update = (model: Model, message: Message) =>
     WidenedPastDrawer: () => closeDrawer(model, false),
     CompletedShowRailDrawer: () => ({ model }),
     CompletedHideRailDrawer: () => ({ model }),
+    CompletedFocusRailToggle: () => ({ model }),
   });
 
 // DRAWER EVENTS
@@ -238,7 +277,7 @@ type DrawerMessage =
   | typeof Message.WidenedPastDrawer.Type;
 
 /** The width at and under which the rail is a drawer, as the stylesheet has it. */
-const DRAWER_QUERY = "(max-width: 900px)";
+export const DRAWER_QUERY = "(max-width: 900px)";
 
 /** The window crossing the drawer's width: growing past it while the drawer is open closes
  *  the drawer, since the rail is back in the page there. */
@@ -351,10 +390,17 @@ export type ViewInputs = Readonly<{
    *  (for this client: another reader's window is not this one's); none for the stylesheet's.
    *  A width out of the rail's bounds prints at the nearer bound. */
   maybeWidth: Option.Option<number>;
-  /** The rail's panels: a tree, places, filters. A function because a Submodel's viewInputs
-   *  may hold functions only at the top level, and Foldkit runs this one in the parent's
-   *  boundary, so the handlers in what it returns dispatch the parent's Messages. */
-  toAsideView: () => ReadonlyArray<Html>;
+  /** Whether the reader folded the rail to its first panel's title bar, as the parent keeps it
+   *  from `ToggledRail` (for this client, as it keeps the width). The drawer ignores it. */
+  isHidden: boolean;
+  /** The parent's key for the toggle, which its tip prints after its label; the parent binds
+   *  it to `toggle`. */
+  maybeToggleKeyHint: Option.Option<Button.KeyHintConfig>;
+  /** The rail's panels: a tree, places, filters, given the toggle that folds the rail to put in
+   *  its first panel's `lead`. A function because a Submodel's viewInputs may hold functions
+   *  only at the top level, and Foldkit runs this one in the parent's boundary, so the
+   *  handlers in what it returns dispatch the parent's Messages. */
+  toAsideView: (toggle: Html) => ReadonlyArray<Html>;
   /** The page beside the rail, `main.deck#main` or `main.bench#main`, given the button that
    *  opens the drawer to print first in it. A function because it receives that button, and
    *  runs in the parent's boundary like `toAsideView`. */
@@ -362,10 +408,11 @@ export type ViewInputs = Readonly<{
 }>;
 
 /**
- * A column of panels beside the deck, fixed under the top bar and scrolling itself:
- * `div.railed >` the deck, then `aside.rail[popover="auto"][aria-label]`, then its splitter,
- * `div.rail-resize[role="separator"]`, on its right edge. One element serves both layouts, so
- * nothing in it renders twice or loses its state. At 900px and under it leaves the page, and
+ * A column of panels beside the deck, fixed under the top bar: `div.railed >` the deck, then
+ * `aside.rail[popover="auto"][aria-label]`, then its splitter, `div.rail-resize[role="separator"]`,
+ * on its right edge. What comes before its last panel keeps its height, and the last panel
+ * shrinks to the room left, its bar and foot staying while its body scrolls. One element
+ * serves both layouts, so nothing in it renders twice or loses its state. At 900px and under it leaves the page, and
  * `span.rail-open > button.btn.small` at the top of the deck opens the same element as a drawer
  * over a veil, its head (the name and a close glyph) showing. Opening focuses its first
  * control; Escape, a press on the veil, the close glyph, focus leaving or the window growing
@@ -373,16 +420,23 @@ export type ViewInputs = Readonly<{
  *
  * Its splitter sizes it, by a pointer (previewed as it moves) or the side arrows, within its
  * bounds, and reports the width as `ResizedRail` for the parent to keep and pass back as
- * `maybeWidth`, which the view sets as `--rail` on `div.railed`, so the page's padding and the
- * rail's width follow it. The drawer keeps its own width. Lift `subscriptions(keyPrefix)` into
- * the application's, or a dragged splitter follows nothing.
+ * `maybeWidth`, which the view sets as `--railed-width` on `div.railed`, so the page's padding
+ * and the rail's width follow it (without one, `--rail`). The drawer keeps its own width. Lift
+ * `subscriptions(keyPrefix)` into the application's, or a dragged splitter follows nothing.
+ *
+ * Its toggle, `span.rail-toggle > button.iconbtn.quiet[aria-expanded]` ("Hide <label>"), comes
+ * to `toAsideView` to print as the first panel's `lead`. Pressed, it reports `ToggledRail` for
+ * the parent to keep and pass back as `isHidden`: `div.railed.folded` then stands the first
+ * panel's title bar on end on the ground (the toggle at its top, "Show <label>"), the rest of
+ * the rail and its splitter gone, and the deck takes the width. Focus in the rail lands on the
+ * toggle. The drawer, at 900px and under, prints neither the toggle nor the fold.
  *
  * Its state is its own, not `@foldkit/ui`'s Popover: that panel is placed by Floating UI and
  * rendered only while open, and this one is always in the page, placed by the stylesheet, and
  * opened as a native popover so the browser keeps it in the top layer.
  */
 export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { label, toAsideView, toDeckView } = viewInputs;
+  const { label, isHidden, maybeToggleKeyHint, toAsideView, toDeckView } = viewInputs;
   const maybeWidth = Option.orElse(
     Option.map(model.maybeResizing, ({ width }) => width),
     () => Option.map(viewInputs.maybeWidth, bounded),
@@ -409,12 +463,58 @@ export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h
     ],
   );
 
+  const toggleButton = h.span(
+    [h.Class("rail-toggle")],
+    [
+      IconButton.view(
+        {
+          glyph: "sidebar",
+          label: `${isHidden ? "Show" : "Hide"} ${label}`,
+          isQuiet: true,
+          onClick: Message.ClickedToggle(),
+          ...Option.match(maybeToggleKeyHint, {
+            onNone: () => ({}),
+            onSome: (keyHint) => ({ keyHint }),
+          }),
+          attributes: [h.Id(toggleId(model)), h.AriaExpanded(!isHidden), h.AriaControls(model.id)],
+        },
+        h,
+      ),
+    ],
+  );
+
+  const splitter = h.div([
+    h.Class("rail-resize"),
+    h.Role("separator"),
+    h.AriaLabel(`Width of ${label}`),
+    h.AriaControls(model.id),
+    h.AriaValuemin(WIDTH.least),
+    h.AriaValuemax(WIDTH.most),
+    h.AriaValuenow(width),
+    h.AriaValuetext(`${width} pixels`),
+    h.Tabindex(0),
+    ...splitterAttributes(
+      {
+        orientation: "vertical",
+        isIdle: Option.isNone(model.maybeResizing),
+        onPress: (pointerId, clientX) => Message.PressedSplitter({ pointerId, clientX, width }),
+        onStep: (direction) =>
+          Message.PressedSplitterKey({ width: width + direction * WIDTH.step }),
+      },
+      h,
+    ),
+  ]);
+
   // NOTE: the deck comes first so the page's main content, and its h1, precede the rail's
   // panels in reading order; the stylesheet places the rail, fixed, at the left.
   return h.div(
     [
-      h.Class("railed"),
-      ...Array.fromOption(Option.map(maybeWidth, (shown) => h.Style({ "--rail": `${shown}px` }))),
+      h.Class(isHidden ? "railed folded" : "railed"),
+      ...(isHidden
+        ? []
+        : Array.fromOption(
+            Option.map(maybeWidth, (shown) => h.Style({ "--railed-width": `${shown}px` })),
+          )),
     ],
     [
       toDeckView(openButton),
@@ -437,30 +537,10 @@ export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h
               ),
             ],
           ),
-          ...toAsideView(),
+          ...toAsideView(toggleButton),
         ],
       ),
-      h.div([
-        h.Class("rail-resize"),
-        h.Role("separator"),
-        h.AriaLabel(`Width of ${label}`),
-        h.AriaControls(model.id),
-        h.AriaValuemin(WIDTH.least),
-        h.AriaValuemax(WIDTH.most),
-        h.AriaValuenow(width),
-        h.AriaValuetext(`${width} pixels`),
-        h.Tabindex(0),
-        ...splitterAttributes(
-          {
-            orientation: "vertical",
-            isIdle: Option.isNone(model.maybeResizing),
-            onPress: (pointerId, clientX) => Message.PressedSplitter({ pointerId, clientX, width }),
-            onStep: (direction) =>
-              Message.PressedSplitterKey({ width: width + direction * WIDTH.step }),
-          },
-          h,
-        ),
-      ]),
+      ...(isHidden ? [] : [splitter]),
     ],
   );
 });

package/src/reel/layout.ts

@@ -247,6 +247,11 @@ export const apply = (layout: Layout, request: OutMessage): Layout =>
       })),
   });
 
+/** Whether `request` changes `layout`: a move, a drop or a stop that would leave it as it is
+ *  is passed over. */
+export const isChange = (layout: Layout, request: OutMessage): boolean =>
+  !Equal.equals(apply(layout, request), layout);
+
 // WIDTHS
 
 /** How close a width is to a preset to count as it. */
@@ -349,7 +354,7 @@ export const requestOf = (
         OutMessage.MovedPane({ paneId, toColumnId: columnId, toIndex: index }),
       Gap: ({ maybeBeforeColumnId }) => OutMessage.PulledOutPane({ paneId, maybeBeforeColumnId }),
     }),
-    (request) => !Equal.equals(apply(layout, request), layout),
+    (request) => isChange(layout, request),
   );
 
 /** Where the pane `paneId` would be once dropped at `target`, in words. */
@@ -469,13 +474,11 @@ export const steppedTarget = (
 const EDGE_SHARE = 0.2;
 const EDGE_MAX = 48;
 
-/** A column as a pointer reads it: its id, its left and right edges, and the vertical middles
- *  of its slots, the held pane's left out. */
+/** A column as a pointer reads it: its id and its left and right edges. */
 export type ColumnBox = Readonly<{
   id: string;
   left: number;
   right: number;
-  slotMiddles: ReadonlyArray<number>;
 }>;
 
 const gapBefore = (columns: ReadonlyArray<ColumnBox>, gap: number): Target =>
@@ -484,18 +487,22 @@ const gapBefore = (columns: ReadonlyArray<ColumnBox>, gap: number): Target =>
 /** Where a pointer at (`clientX`, `clientY`) over a reel whose columns sit at `columns`, left
  *  to right, would drop a pane. Over a column's edge band (or over a gap, or past the last
  *  column) it lands in that gap, as a column of its own; over the rest of a column it lands
- *  among that column's other panes, after each whose middle is above the pointer. */
+ *  among that column's other panes, after each whose middle is above the pointer.
+ *  `slotMiddlesOf` gives the vertical middles of a column's slots, by its index, the held
+ *  pane's left out: it is asked for the column the pointer is over alone, and only when the
+ *  pointer is among its panes. */
 export const targetAtPoint = (
   columns: ReadonlyArray<ColumnBox>,
   clientX: number,
   clientY: number,
+  slotMiddlesOf: (index: number) => ReadonlyArray<number>,
 ): Target =>
   pipe(
     Array.findFirstIndex(columns, ({ right }) => clientX <= right),
     Option.flatMap((index) => Option.map(Array.get(columns, index), (box) => ({ index, box }))),
     Option.match({
       onNone: () => gapBefore(columns, columns.length),
-      onSome: ({ index, box: { id, left, right, slotMiddles } }) => {
+      onSome: ({ index, box: { id, left, right } }) => {
         const band = Math.min((right - left) * EDGE_SHARE, EDGE_MAX);
         if (clientX < left + band) {
           return gapBefore(columns, index);
@@ -504,7 +511,7 @@ export const targetAtPoint = (
         } else {
           return Target.Into({
             columnId: id,
-            index: Array.filter(slotMiddles, (middle) => middle < clientY).length,
+            index: Array.filter(slotMiddlesOf(index), (middle) => middle < clientY).length,
           });
         }
       },