@gjermundgaraba-designs/pixel-paper 0.23.0 → 0.24.0

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/tips/tips.ts

@@ -1,4 +1,15 @@
-import { Array, Duration, Effect, Match, Number, Option, Schema, Stream, pipe } from "effect";
+import {
+  Array,
+  Duration,
+  Effect,
+  Equal,
+  Match,
+  Number,
+  Option,
+  Schema,
+  Stream,
+  pipe,
+} from "effect";
 import * as Command from "foldkit/command";
 import * as Dom from "foldkit/dom";
 import type { Html } from "foldkit/html";
@@ -23,7 +34,10 @@ type Side = typeof Side.Type;
 export const Trigger = Schema.Literals(["Pointer", "Focus"]);
 export type Trigger = typeof Trigger.Type;
 
-const Words = { text: Schema.String, side: Side };
+/** 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 ShownWords = { ...Words, trigger: Trigger };
 
 /** Where the page's tip is. `Cold`: none lately. `Waiting`: a pointer rests on a control, for
@@ -51,10 +65,10 @@ export type Model = typeof Model.Type;
 
 /** Union of all Messages the tip layer can produce. */
 export const Message = defineMessageUnion({
-  EnteredTipTarget: { text: Schema.String, side: Side },
+  EnteredTipTarget: Words,
   LeftTipTarget: {},
   EnteredTip: {},
-  FocusedTipTarget: { text: Schema.String, side: Side },
+  FocusedTipTarget: Words,
   BlurredTipTarget: {},
   PressedPointer: {},
   PressedKey: {},
@@ -103,6 +117,9 @@ 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}]`;
 
 const hasText = (element: HTMLElement, text: string): boolean =>
@@ -204,9 +221,11 @@ export const WaitBeforeCooling = Command.define("WaitBeforeCooling", {
 
 type UpdateReturn = Update.Return<Model, Message>;
 
-const show = (model: Model, text: string, side: Side, trigger: Trigger): UpdateReturn => ({
-  model: modifyFields(model, { state: () => TipState.Shown({ text, side, trigger }) }),
-  commands: [ShowTip({ tipId: model.id, text, trigger })],
+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 }) }),
+  commands: [ShowTip({ tipId: model.id, text: words.text, trigger })],
 });
 
 const hide = (model: Model): UpdateReturn => {
@@ -217,12 +236,12 @@ const hide = (model: Model): UpdateReturn => {
   };
 };
 
-const wait = (model: Model, text: string, side: Side): UpdateReturn => {
+const wait = (model: Model, words: Words): UpdateReturn => {
   const nextVersion = Number.increment(model.version);
   return {
     model: modifyFields(model, {
       version: () => nextVersion,
-      state: () => TipState.Waiting({ text, side }),
+      state: () => TipState.Waiting(wordsOf(words)),
     }),
     commands: [WaitBeforeShowing({ version: nextVersion })],
   };
@@ -233,7 +252,7 @@ const leave = (model: Model, shown: typeof TipState.Shown.Type): UpdateReturn =>
   return {
     model: modifyFields(model, {
       version: () => nextVersion,
-      state: () => TipState.Leaving({ text: shown.text, side: shown.side, trigger: shown.trigger }),
+      state: () => TipState.Leaving({ ...wordsOf(shown), trigger: shown.trigger }),
     }),
     commands: [WaitBeforeHiding({ version: nextVersion })],
   };
@@ -253,26 +272,26 @@ const dismiss = (model: Model): UpdateReturn =>
     Warm: () => ({ model }),
   });
 
-const entered = (model: Model, text: string, side: Side): UpdateReturn =>
+const entered = (model: Model, words: Words): UpdateReturn =>
   TipState.match<UpdateReturn>(model.state, {
-    Cold: () => wait(model, text, side),
-    Waiting: (waiting) => (waiting.text === text ? { model } : wait(model, text, side)),
-    Shown: (shown) => (shown.text === text ? { model } : show(model, text, side, "Pointer")),
+    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")),
     Leaving: (leaving) =>
-      leaving.text === text
+      leaving.text === words.text
         ? {
             model: modifyFields(model, {
-              state: () => TipState.Shown({ text, side, trigger: leaving.trigger }),
+              state: () => TipState.Shown({ ...wordsOf(words), trigger: leaving.trigger }),
             }),
           }
-        : show(model, text, side, "Pointer"),
-    Warm: () => show(model, text, side, "Pointer"),
+        : show(model, words, "Pointer"),
+    Warm: () => show(model, words, "Pointer"),
   });
 
 /** Processes a tip layer Message and returns the next Model and Commands. */
 export const update = (model: Model, message: Message) =>
   Message.match<UpdateReturn>(message, {
-    EnteredTipTarget: ({ text, side }) => entered(model, text, side),
+    EnteredTipTarget: (words) => entered(model, wordsOf(words)),
     LeftTipTarget: () =>
       TipState.matchOrElse<UpdateReturn>(
         model.state,
@@ -286,13 +305,15 @@ export const update = (model: Model, message: Message) =>
       TipState.matchOrElse<UpdateReturn>(
         model.state,
         {
-          Leaving: ({ text, side, trigger }) => ({
-            model: modifyFields(model, { state: () => TipState.Shown({ text, side, trigger }) }),
+          Leaving: (leaving) => ({
+            model: modifyFields(model, {
+              state: () => TipState.Shown({ ...wordsOf(leaving), trigger: leaving.trigger }),
+            }),
           }),
         },
         () => ({ model }),
       ),
-    FocusedTipTarget: ({ text, side }) => show(model, text, side, "Focus"),
+    FocusedTipTarget: (words) => show(model, wordsOf(words), "Focus"),
     BlurredTipTarget: () => dismiss(model),
     PressedPointer: () => dismiss(model),
     PressedKey: () => dismiss(model),
@@ -300,8 +321,8 @@ export const update = (model: Model, message: Message) =>
       TipState.matchOrElse<UpdateReturn>(
         model.state,
         {
-          Waiting: ({ text, side }) =>
-            model.version === version ? show(model, text, side, "Pointer") : { model },
+          Waiting: (waiting) =>
+            model.version === version ? show(model, wordsOf(waiting), "Pointer") : { model },
         },
         () => ({ model }),
       ),
@@ -328,10 +349,15 @@ type TargetMessage =
   | typeof Message.LeftTipTarget.Type
   | typeof Message.EnteredTip.Type;
 
-type TipTarget = Readonly<{ element: HTMLElement; text: string; side: Side }>;
+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 ? "Top" : "Right";
+  element.closest('[aria-orientation="vertical"]') === null &&
+  !getComputedStyle(element).writingMode.startsWith("vertical")
+    ? "Top"
+    : "Right";
 
 const tipTargetOf = (target: EventTarget | null): Option.Option<TipTarget> =>
   pipe(
@@ -341,6 +367,7 @@ const tipTargetOf = (target: EventTarget | null): Option.Option<TipTarget> =>
       Option.map(Option.fromNullishOr(element.getAttribute(TIP_ATTRIBUTE)), (text) => ({
         element,
         text,
+        maybeKey: Option.fromNullishOr(element.getAttribute(TIP_KEY_ATTRIBUTE)),
         side: sideOf(element),
       })),
     ),
@@ -366,7 +393,7 @@ export const pointerOverMessage = (
   return Option.some(
     Option.match(tipTargetOf(event.target), {
       onNone: () => Message.LeftTipTarget(),
-      onSome: ({ text, side }) => Message.EnteredTipTarget({ text, side }),
+      onSome: (target) => Message.EnteredTipTarget(wordsOf(target)),
     }),
   );
 };
@@ -376,7 +403,7 @@ export const pointerOverMessage = (
 const focusInMessage = (event: FocusEvent): Option.Option<Message> =>
   Option.map(
     Option.filter(tipTargetOf(event.target), ({ element }) => element.matches(":focus-visible")),
-    ({ text, side }) => Message.FocusedTipTarget({ text, side }),
+    (target) => Message.FocusedTipTarget(wordsOf(target)),
   );
 
 /** Focus leaving a control with a tip, not into a part of itself, closes the tip (and
@@ -421,7 +448,9 @@ const pointerOverChanges = (tipId: string): Stream.Stream<Message> =>
 const sameWords = (previous: Message, next: Message): boolean =>
   previous._tag !== "EnteredTipTarget" ||
   next._tag !== "EnteredTipTarget" ||
-  (previous.text === next.text && previous.side === next.side);
+  (previous.text === next.text &&
+    previous.side === next.side &&
+    Equal.equals(previous.maybeKey, next.maybeKey));
 
 const tipSubscriptions = Subscription.make<Model, Message>()((entry) => ({
   pointerAndFocus: entry(
@@ -480,16 +509,17 @@ export const subscriptions = <Prefix extends string>(keyPrefix: Prefix) =>
 
 // VIEW
 
-const wordsOf = (model: Model): Option.Option<Readonly<{ text: string; side: Side }>> =>
+const maybeWordsOf = (model: Model): Option.Option<Words> =>
   Match.value(model.state).pipe(
-    Match.withReturnType<Option.Option<Readonly<{ text: string; side: Side }>>>(),
-    Match.tag("Waiting", "Shown", "Leaving", ({ text, side }) => Option.some({ text, side })),
+    Match.withReturnType<Option.Option<Words>>(),
+    Match.tag("Waiting", "Shown", "Leaving", (words) => Option.some(wordsOf(words))),
     Match.orElse(() => Option.none()),
   );
 
 /**
  * The page's one tip: `div.tip[popover="manual"][aria-hidden="true"]`, which shows the words
- * of any control carrying `data-tip` (IconButton, the glyph switch, a board's grip). Render it
+ * of any control carrying `data-tip` (IconButton, the glyph switch, a board's grip), then the
+ * key in its `data-tip-key` where it has one (an IconButton's `keyHint`). Render it
  * once, beside the Announcer, and lift `subscriptions(keyPrefix)`. It opens on a resting
  * pointer after a moment (at once while another has just closed), never on touch, and on
  * keyboard focus; it can be hovered; leaving, blur, a press or any key closes it, and Escape
@@ -501,7 +531,7 @@ const wordsOf = (model: Model): Option.Option<Readonly<{ text: string; side: Sid
  * accessibility tree, and any control takes one by carrying `data-tip`.
  */
 export const view = defineView<Model, Message>((model, h): Html => {
-  const maybeWords = wordsOf(model);
+  const maybeWords = maybeWordsOf(model);
 
   return h.div(
     [
@@ -513,6 +543,12 @@ export const view = defineView<Model, Message>((model, h): Html => {
         ? [h.DataAttribute("side", "right")]
         : []),
     ],
-    Option.isSome(maybeWords) ? [maybeWords.value.text] : [],
+    Option.match(maybeWords, {
+      onNone: () => [],
+      onSome: ({ text, maybeKey }) => [
+        text,
+        ...Array.fromOption(Option.map(maybeKey, (key) => h.kbd([h.Class("key-hint")], [key]))),
+      ],
+    }),
   );
 });

package/src/tokens.css

@@ -127,6 +127,7 @@
   --deck: 1160px; /* the widest a deck of panels runs */
   --rail: 272px; /* the column of panels beside a deck, until the reader sizes it */
   --rail-drawer: 320px; /* the rail as a drawer, whatever width the reader gave it */
+  --rail-folded: 64px; /* the rail folded to its first panel's bar, stood on end */
 
   /* ---------- space: between components (Stack, Group, Wrap) ---------- */
   --space-s: 8px; /* things in one line: buttons, chips, a glyph and its word */