@gjermundgaraba-designs/pixel-paper 0.23.0 → 0.25.0

package/src/pixel-paper.css

@@ -979,6 +979,19 @@ a.textbtn {
   flex: 1 1 100%;
 }
 
+/* the shelf: a strip on the head tint under the bar, for a field that picks what the body
+   shows */
+.panel-shelf {
+  padding: 10px 12px 12px;
+  background: var(--head);
+  border-bottom: var(--hair) solid var(--rule);
+}
+
+/* on the head tint a field's label takes on-head: muted misses AA there */
+.panel-shelf :is(.field > label:not(.choice), .field-label) {
+  color: var(--on-head);
+}
+
 /* ---------- the panel's title-bar lead and actions ---------- */
 
 /* small buttons and icon buttons at the bar's right end, and an icon button before the
@@ -4828,6 +4841,16 @@ dialog.veil:focus {
   overflow: visible;
 }
 
+/* the key that does the same as the control, after its words, as a button prints it */
+.tip .key-hint {
+  margin-left: 6px;
+  font-family: var(--font-px);
+  font-size: var(--type-label);
+  text-transform: none;
+  letter-spacing: 0;
+  opacity: var(--fade-on-ink);
+}
+
 /* ---------- toolbars: one strip of tools, one stop for Tab ---------- */
 
 /* the rules between tools are the strip's ink showing through a 2px gap */
@@ -5022,8 +5045,7 @@ dialog.veil:focus {
 /* ---------- the rail: a column of panels beside the deck, a drawer on a phone ---------- */
 
 /* one element in two places: at rest, fixed down the left edge from the top bar's lower
-   edge (as the stage hangs) and scrolling itself; on a phone the same element opens as a
-   popover drawer. The reader's width, when they gave one, is --railed-width, which the view
+   edge (as the stage hangs); on a phone the same element opens as a popover drawer. The reader's width, when they gave one, is --railed-width, which the view
    sets on .railed, so the page's padding and the rail's width follow it together; without one,
    --rail. It is not inherited: each box it sizes takes it from .railed by name, so a width that
    changes under a dragged splitter restyles those four and none of the rows inside them */
@@ -5046,8 +5068,8 @@ dialog.veil:focus {
   top: anchor(--topbar bottom, 0px);
   bottom: var(--statusbar-h);
   left: 0;
-  display: grid;
-  align-content: start;
+  display: flex;
+  flex-direction: column;
   gap: var(--gap);
   width: var(--railed-width, var(--rail));
   height: auto;
@@ -5059,7 +5081,43 @@ dialog.veil:focus {
 }
 
 .rail > * {
+  flex: none;
+  min-width: 0;
+}
+
+/* the rail's top stays put: what comes before its last panel keeps its height, and the last
+   panel takes the room left, at most its own height, its bar, shelf and foot staying while
+   its body scrolls (the padded body, or a flush body's list). The rail scrolls as a whole
+   only when what comes before that panel is taller than the column */
+.rail > .panel:last-child {
+  display: flex;
+  flex-direction: column;
+  flex: 0 1 auto;
+  min-height: 0;
+}
+
+.rail > .panel:last-child > :is(.panel-tb, .panel-shelf, .panel-foot) {
+  flex: none;
+}
+
+.rail > .panel:last-child > :not(.panel-tb, .panel-shelf, .panel-foot) {
+  flex: 0 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+}
+
+/* a long name ends short of the bar's tools rather than wrapping the bar taller */
+.rail .panel-tb h2 {
   min-width: 0;
+  overflow: hidden;
+  overflow-wrap: normal;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/* the toggle is the button itself in the bar's lead */
+.rail-toggle {
+  display: contents;
 }
 
 /* the splitter on the rail's right edge: a 12px strip from the edge outward, over the page's
@@ -5102,6 +5160,48 @@ dialog.veil:focus {
   display: none;
 }
 
+/* folded: the first panel stands its title bar on end on the ground where the rail stood, the
+   toggle at its top and the title and count reading down; the rest of the rail and the
+   splitter are gone, and the deck takes the width. Above 900px only: the drawer opens whole.
+   Folding and unfolding move in three steps, as the drawer enters, but never while a pointer
+   drags the splitter, where the rail follows the pointer */
+@media not (max-width: 900px) {
+  .railed.folded {
+    --railed-width: var(--rail-folded);
+  }
+
+  .railed.folded > .rail > :not(.rail-head + .panel),
+  .railed.folded > .rail > .rail-head + .panel > :not(.panel-tb),
+  .railed.folded > .rail > .rail-head + .panel > .panel-tb > .panel-acts {
+    display: none;
+  }
+
+  .railed.folded > .rail > .rail-head + .panel {
+    align-self: flex-start;
+  }
+
+  .railed.folded > .rail > .rail-head + .panel > .panel-tb {
+    writing-mode: vertical-rl;
+    min-width: 31px;
+    min-height: 0;
+    padding: 3px 3px 12px;
+  }
+
+  .railed.folded > .rail > .rail-head + .panel > .panel-tb > .meta {
+    margin: 0;
+  }
+
+  .railed,
+  .railed > :is(.rail, .bench) {
+    transition: var(--motion-card) steps(3, end);
+    transition-property: padding-left, width, left;
+  }
+
+  :root[data-pixel-paper-dragging] :is(.railed, .railed > .rail, .railed > .bench) {
+    transition: none;
+  }
+}
+
 @media (max-width: 900px) {
   .railed {
     padding-left: 0;
@@ -5140,6 +5240,16 @@ dialog.veil:focus {
     display: inline-flex;
     justify-self: start;
   }
+
+  /* the drawer opens and closes but never folds, so it prints no toggle, and the bar the
+     toggle led keeps its own padding */
+  .panel-lead:has(> .rail-toggle) {
+    display: none;
+  }
+
+  .panel-tb:has(> .panel-lead > .rail-toggle) {
+    padding-left: 12px;
+  }
 }
 
 @keyframes railIn {
@@ -5520,6 +5630,54 @@ dialog.veil:focus {
   opacity: var(--fade-dragged);
 }
 
+/* under tabs, the reel is its tab list over the scroller, which takes the height left. The
+   list sits a gutter in from the reel's edges, as the windows do */
+.reel.tabbed {
+  display: flex;
+  flex-direction: column;
+}
+
+.reel.tabbed > .reel-view {
+  flex: 1 1 0;
+  height: auto;
+  min-height: 0;
+}
+
+.reel-tabs {
+  flex: none;
+  max-width: calc(100% - 2 * var(--reel-gutter));
+  margin: var(--reel-gutter) var(--reel-gutter) 0;
+}
+
+/* a tab holds a kind glyph before its words, and gives up width before the list overflows:
+   its words end in an ellipsis */
+.reel-tabs button {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.reel-tab-words {
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* the one slot under tabs: the view less a gutter at every edge, every pane pinned to it */
+.reel-stage {
+  flex: 1 1 0;
+  height: calc(100cqh - 2 * var(--reel-gutter));
+  min-height: 0;
+  margin-inline: var(--reel-gutter);
+}
+
+/* a pane behind the selected tab keeps its place and its size, so what sizes itself by its
+   box (a terminal) is not resized as the tabs change; it is only not drawn */
+.reel-pane.behind {
+  visibility: hidden;
+}
+
 /* only the grips lift: a pane's text selects and its terminal takes the pointer */
 [data-reel-grip] {
   cursor: grab;
@@ -5842,4 +6000,9 @@ dialog.veil:focus {
   .toasts .toast {
     animation: none;
   }
+
+  .railed,
+  .railed > :is(.rail, .bench) {
+    transition: none;
+  }
 }

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;
 
@@ -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
@@ -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
@@ -377,12 +424,19 @@ export type ViewInputs = Readonly<{
  * 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,14 +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({ "--railed-width": `${shown}px` })),
-      ),
+      h.Class(isHidden ? "railed folded" : "railed"),
+      ...(isHidden
+        ? []
+        : Array.fromOption(
+            Option.map(maybeWidth, (shown) => h.Style({ "--railed-width": `${shown}px` })),
+          )),
     ],
     [
       toDeckView(openButton),
@@ -439,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/index.ts

@@ -2,7 +2,9 @@ export { Layout, OutMessage, Pane, apply } from "./layout.ts";
 export {
   Action,
   AnnounceReel,
+  Arrangement,
   FocusPane,
+  FocusTab,
   Message,
   Model,
   RestoreFocus,