@gjermundgaraba-designs/pixel-paper 0.23.0 → 0.25.0

package/src/reel/reel.ts

@@ -86,6 +86,7 @@ const COPY = {
   widthLabel: "Width of column {column}",
   heightLabel: "Height of {pane}",
   focused: "{pane}, {where}.",
+  focusedTab: "{pane}, tab {tab} of {tabs}.",
   moved: "{subject} moved to {where}.",
   widened: "Column {column} takes {width}.",
   pickedUp: "Picked up {subject}.",
@@ -143,6 +144,12 @@ export const Model = Schema.Struct({
 });
 export type Model = typeof Model.Type;
 
+/** How a reel shows its panes: side by side in their columns (`Strip`), or one at a time at
+ *  the reel's full size under a tab per pane (`Tabs`). The application holds it and passes it
+ *  in; the layout is the same in both. */
+export const Arrangement = Schema.Literals(["Strip", "Tabs"]);
+export type Arrangement = typeof Arrangement.Type;
+
 // MESSAGE
 
 const PointerAt = Schema.Struct({
@@ -169,6 +176,8 @@ export const Message = defineMessageUnion({
   LeftGrip: {},
   PressedEscape: {},
   FocusedPane: { paneId: Schema.String },
+  PressedTab: { paneId: Schema.String },
+  SteppedTab: { paneId: Schema.String },
   PressedSplitter: {
     splitter: Splitter,
     pointerId: Schema.Number,
@@ -181,6 +190,7 @@ export const Message = defineMessageUnion({
   PressedSplitterKey: { splitter: Splitter, share: Schema.Number },
   CompletedAnnounceReel: {},
   CompletedFocusPane: {},
+  CompletedFocusTab: {},
   CompletedRestoreFocus: {},
   CompletedScrollIntoView: {},
   CompletedSizeLiftedPane: {},
@@ -238,6 +248,8 @@ const paneHook = (model: Model, paneId: string): string => `${model.id}/pane/${p
 
 const columnHook = (model: Model, columnId: string): string => `${model.id}/column/${columnId}`;
 
+const tabHook = (model: Model, paneId: string): string => `${model.id}/tab/${paneId}`;
+
 const scrollerOf = (reelHook: string): Option.Option<HTMLElement> =>
   Option.fromNullishOr(
     document.querySelector<HTMLElement>(`[data-reel="${CSS.escape(reelHook)}"] > .reel-view`),
@@ -286,6 +298,21 @@ export const FocusPane = Command.define("FocusPane", {
     }),
 });
 
+/** Focuses the tab `tabHook` names, for a tab the arrows step to: the keyboard stays in the
+ *  tab list until the reader goes into the pane. */
+export const FocusTab = Command.define("FocusTab", {
+  args: { tabHook: Schema.String },
+  messages: [Message.CompletedFocusTab],
+  execute: ({ tabHook: hook }) =>
+    Effect.gen(function* () {
+      yield* Render.afterCommit;
+      yield* Effect.sync(() => {
+        document.querySelector<HTMLElement>(`[data-reel-tab="${CSS.escape(hook)}"]`)?.focus();
+      });
+      return Message.CompletedFocusTab();
+    }),
+});
+
 /** Focuses the pane `paneHook` names only where focus was lost (it left with the pane that
  *  held it), so focus the reader put somewhere else stays there. */
 export const RestoreFocus = Command.define("RestoreFocus", {
@@ -327,8 +354,9 @@ export const ScrollIntoView = Command.define("ScrollIntoView", {
 // UPDATE
 
 /** What the reel reads from its parent as each Message arrives: the layout as the
- *  application holds it now. */
-export type UpdateContext = Readonly<{ layout: Layout }>;
+ *  application holds it now, and how the view shows it (`Strip` when not given), which
+ *  `perform` reads. */
+export type UpdateContext = Readonly<{ layout: Layout; arrangement?: Arrangement }>;
 
 type UpdateReturn = Update.ReturnWithOutMessage<Model, Message, OutMessage>;
 
@@ -497,6 +525,19 @@ const resizeSplitter = (
     },
   });
 
+/** Shows the pane `paneId` under its tab and moves the keyboard as `focus` says: into the
+ *  pane for a press, onto the tab for an arrow. */
+const selectTab = (
+  model: Model,
+  layout: Layout,
+  paneId: string,
+  focus: Command.Command<Message>,
+): UpdateReturn =>
+  Option.match(placeOf(layout, paneId), {
+    onNone: () => ({ model }),
+    onSome: (place) => ({ model: focusOn(model, place), commands: [focus] }),
+  });
+
 /** Processes a reel Message against the layout as the application holds it now, and returns
  *  the next Model, Commands and OutMessage. */
 export const update = (model: Model, message: Message, context: UpdateContext): UpdateReturn => {
@@ -542,6 +583,10 @@ export const update = (model: Model, message: Message, context: UpdateContext):
       Option.isSome(model.maybeResizing)
         ? { model: withResizing(model, Option.none()) }
         : whileHeld(model, (held) => cancel(model, layout, held)),
+    PressedTab: ({ paneId }) =>
+      selectTab(model, layout, paneId, FocusPane({ paneHook: paneHook(model, paneId) })),
+    SteppedTab: ({ paneId }) =>
+      selectTab(model, layout, paneId, FocusTab({ tabHook: tabHook(model, paneId) })),
     FocusedPane: ({ paneId }) =>
       Option.match(
         Option.filter(
@@ -578,6 +623,7 @@ export const update = (model: Model, message: Message, context: UpdateContext):
       }),
     CompletedAnnounceReel: () => ({ model }),
     CompletedFocusPane: () => ({ model }),
+    CompletedFocusTab: () => ({ model }),
     CompletedRestoreFocus: () => ({ model }),
     CompletedScrollIntoView: () => ({ model }),
     CompletedSizeLiftedPane: () => ({ model }),
@@ -700,6 +746,51 @@ const requestStep = (
     },
   );
 
+/** The panes in the order their tabs print: column by column, and down each column. */
+const readingOrder = (layout: Layout): ReadonlyArray<Pane> =>
+  Array.flatMap(layout, (column) => column.panes);
+
+/** How far each focus key steps through the tabs: left and up to the one before, right and
+ *  down to the one after. */
+const TAB_STEPS: Readonly<Partial<Record<Action, number>>> = {
+  FocusLeft: -1,
+  FocusUp: -1,
+  FocusRight: 1,
+  FocusDown: 1,
+};
+
+/** `perform` while the panes print as tabs: a focus key moves to the tab beside the focused
+ *  pane's, past neither end; there is no column to move or size. */
+const performTabbed = (model: Model, action: Action, layout: Layout): UpdateReturn => {
+  const panes = readingOrder(layout);
+  const maybeNext = Option.flatMap(
+    Option.all({
+      step: Option.fromUndefinedOr(TAB_STEPS[action]),
+      index: Option.flatMap(focusedPaneId(model, layout), (paneId) =>
+        Array.findFirstIndex(panes, (pane) => pane.id === paneId),
+      ),
+    }),
+    ({ step, index }) =>
+      Option.flatMap(Array.get(panes, index + step), (pane) =>
+        Option.map(placeOf(layout, pane.id), (place) => ({ place, tab: index + step + 1 })),
+      ),
+  );
+
+  return Option.match(
+    Option.filter(maybeNext, () => !isHolding(model)),
+    {
+      onNone: () => ({ model }),
+      onSome: ({ place, tab }) => ({
+        model: focusOn(model, place),
+        commands: [
+          FocusPane({ paneHook: paneHook(model, place.pane.id) }),
+          announce(fill(COPY.focusedTab, { pane: place.pane.label, tab, tabs: panes.length })),
+        ],
+      }),
+    },
+  );
+};
+
 const columnIdAt = (layout: Layout, index: number): Option.Option<string> =>
   Option.map(Array.get(layout, index), ({ id }) => id);
 
@@ -708,10 +799,15 @@ const columnIdAt = (layout: Layout, index: number): Option.Option<string> =>
  * layout as the application holds it: focus moves focus the pane and scroll the reel to it;
  * moves report their request as the OutMessage, which the application applies, with focus
  * kept on the pane. Each is said through the live region. Nothing happens while something is
- * held, or where there is nowhere to go.
+ * held, or where there is nowhere to go. Under tabs, only the focus keys act, stepping from tab
+ * to tab.
  */
 export const perform = (model: Model, action: Action, context: UpdateContext): UpdateReturn => {
-  const { layout } = context;
+  const { layout, arrangement = "Strip" } = context;
+
+  if (arrangement === "Tabs") {
+    return performTabbed(model, action, layout);
+  }
 
   return Option.match(
     Option.filter(focusedPlace(model, layout), () => !isHolding(model)),
@@ -1157,11 +1253,12 @@ export const SizeLiftedPane = Mount.define("SizeLiftedPane", {
 
 // VIEW
 
-/** What the reel hands `toPaneView` for each pane: put `grip` in the Window's `lead` and give
+/** What the reel hands `toPaneView` for each pane: put `lead` in the Window's `lead` and give
  *  it `id`. */
 export type PaneRender = Readonly<{
-  /** The pane's grip, for its title bar's `lead`: a quiet glyph button named "Move <label>". */
-  grip: Html;
+  /** The title bar's `lead`: the pane's grip, a quiet glyph button named "Move <label>", or
+   *  nothing under tabs, where a pane does not move. */
+  lead: ReadonlyArray<Html>;
   /** The window's id, unique in the document. */
   id: string;
 }>;
@@ -1173,15 +1270,21 @@ export type ViewInputs = Readonly<{
   layout: Layout;
   /** Names the reel for screen readers. */
   label: string;
-  /** Renders one pane, a `Window.view` with `render.grip` as its `lead` and `render.id` as its
+  /** Renders one pane, a `Window.view` with `render.lead` as its `lead` and `render.id` as its
    *  `id`. Mark the control focus should land on in it (a terminal's input) with
    *  `data-reel-focus`. */
   toPaneView: (pane: Pane, render: PaneRender) => Html;
+  /** How the panes print: in their columns (`Strip`, when not given), or one at a time under
+   *  their tabs (`Tabs`). Pass the same to `perform`. */
+  arrangement?: Arrangement;
+  /** What a pane's tab prints before its label: a kind glyph. Nothing when not given. */
+  toTabLeadView?: (pane: Pane) => ReadonlyArray<Html>;
 }>;
 
 type ReelInfo = Readonly<{
   model: Model;
   layout: Layout;
+  isTabbed: boolean;
   toPaneView: (pane: Pane, render: PaneRender) => Html;
   maybeFocusedId: Option.Option<string>;
   maybeMark: Option.Option<Target>;
@@ -1202,6 +1305,9 @@ const HELD_STEPS: Readonly<Record<string, Step>> = {
 
 const isDropKey = (key: string): boolean => key === " " || key === "Enter";
 
+/** The anchor every pane is pinned to under tabs: the one slot, the reel's full size. */
+const STAGE_ANCHOR = "--reel-stage";
+
 /** The anchor that pins a pane to its slot. Pane ids are the application's, so the name is
  *  the pane's place in the id order, which the slot and the pane read from one list. */
 const anchorName = (index: number): string => `--reel-${index}`;
@@ -1406,26 +1512,32 @@ const paneLayerView = (
 ): Html => {
   const { model } = info;
 
-  // NOTE: the panes keep one order in the page, by id, whatever the layout: a move changes
-  // only where each is anchored, so no pane's element is taken out and put back, which would
-  // drop focus, a terminal's scroll and whatever a Mount holds inside it.
+  // NOTE: the panes keep one order in the page, by id, whatever the layout or the arrangement:
+  // a move or a change to tabs changes only where each is anchored, so no pane's element is
+  // taken out and put back, which would drop focus, a terminal's scroll and whatever a Mount
+  // holds inside it. Under tabs the panes behind the focused one are hidden, not removed, and
+  // keep their size, so a terminal sized by its box is not resized as the tabs change.
   return h.div(
     [h.Class("reel-panes")],
     Array.map(panes, (pane) => {
       const isFocused = Option.contains(info.maybeFocusedId, pane.id);
       const isHeld = Option.contains(info.maybeCarriedId, pane.id);
+      const isBehind = info.isTabbed && !isFocused;
       return h.keyed("div")(
         pane.id,
         [
-          h.Class(`reel-pane${isFocused ? " focused" : ""}${isHeld ? " drag-dim" : ""}`),
+          h.Class(
+            `reel-pane${isFocused ? " focused" : ""}${isHeld ? " drag-dim" : ""}${isBehind ? " behind" : ""}`,
+          ),
           h.DataAttribute("reel-pane", paneHook(model, pane.id)),
           h.Style({ "--reel-anchor": anchors.get(pane.id) ?? "none" }),
           h.Tabindex(-1),
+          ...(isBehind ? [h.Inert(true)] : []),
           h.OnFocusEnter(Message.FocusedPane({ paneId: pane.id })),
         ],
         [
           info.toPaneView(pane, {
-            grip: gripView(model, pane, h),
+            lead: info.isTabbed ? [] : [gripView(model, pane, h)],
             id: `${model.id}-${pane.id}`,
           }),
         ],
@@ -1484,6 +1596,57 @@ const liftedCopyView = (info: ReelInfo, h: HtmlBuilder<Message>): ReadonlyArray<
   );
 };
 
+/** The tab list under tabs: a tab per pane in reading order, the focused pane's selected. A
+ *  press shows its pane and puts the keyboard in it; the side arrows (wrapping), Home and End
+ *  select as they move and keep the keyboard on the tabs, only the selected tab being in the
+ *  Tab order. A modified arrow is the application's. */
+const tabListView = (
+  info: ReelInfo,
+  label: string,
+  toTabLeadView: (pane: Pane) => ReadonlyArray<Html>,
+  h: HtmlBuilder<Message>,
+): Html => {
+  const { model, layout } = info;
+  const panes = readingOrder(layout);
+  const stepTo = (index: number): Option.Option<Message> =>
+    Option.map(Array.get(panes, (index + panes.length) % panes.length), ({ id }) =>
+      Message.SteppedTab({ paneId: id }),
+    );
+  const keyOf = (index: number, key: string): Option.Option<Message> =>
+    Match.value(key).pipe(
+      Match.when("ArrowLeft", () => stepTo(index - 1)),
+      Match.when("ArrowRight", () => stepTo(index + 1)),
+      Match.when("Home", () => stepTo(0)),
+      Match.when("End", () => stepTo(panes.length - 1)),
+      Match.orElse(() => Option.none()),
+    );
+
+  return h.div(
+    [h.Class("nav tabs reel-tabs"), h.Role("tablist"), h.AriaLabel(label)],
+    Array.map(panes, (pane, index) => {
+      const isSelected = Option.contains(info.maybeFocusedId, pane.id);
+      return h.keyed("button")(
+        pane.id,
+        [
+          h.Type("button"),
+          h.Role("tab"),
+          h.AriaSelected(isSelected),
+          h.AriaControls(`${model.id}-${pane.id}`),
+          h.Tabindex(isSelected ? 0 : -1),
+          h.DataAttribute("reel-tab", tabHook(model, pane.id)),
+          h.OnClick(Message.PressedTab({ paneId: pane.id })),
+          h.OnKeyDownPreventDefault((key, modifiers) =>
+            isPlain(modifiers) ? keyOf(index, key) : Option.none(),
+          ),
+        ],
+        [...toTabLeadView(pane), h.span([h.Class("reel-tab-words")], [pane.label])],
+      );
+    }),
+  );
+};
+
+const NO_TAB_LEAD = (): ReadonlyArray<Html> => [];
+
 /** The layout as it prints, with a dragged splitter's resize shown before it is asked for. */
 const previewed = (model: Model, layout: Layout): Layout =>
   Option.match(
@@ -1504,48 +1667,75 @@ const previewed = (model: Model, layout: Layout): Layout =>
  * panes), Space drops it, and Escape or Tab puts it back. A drop reports what it asks
  * of the layout as the OutMessage. Lift `subscriptions(keyPrefix)` into the application's, or
  * nothing follows the pointer, and call `reconcile` whenever the layout changes.
+ *
+ * Under tabs (`arrangement: "Tabs"`) the reel is `div.reel.tabbed`: a `div.nav.tabs.reel-tabs`
+ * tab list over the scroller, whose track holds one `div.reel-slot.reel-stage` at the reel's
+ * full size where the columns were. Every pane is pinned to it, the focused one shown and the
+ * others `.behind`, hidden and inert; there are no grips and no splitters.
  */
 export const view = defineView<Model, Message, ViewInputs>((model, viewInputs, h): Html => {
-  const { label, toPaneView } = viewInputs;
+  const { label, toPaneView, arrangement = "Strip", toTabLeadView = NO_TAB_LEAD } = viewInputs;
+  const isTabbed = arrangement === "Tabs";
   const layout = previewed(model, viewInputs.layout);
   const panes = Array.sort(
     Array.flatMap(layout, (column) => column.panes),
     byId,
   );
-  const anchors = new Map(Array.map(panes, (pane, index) => [pane.id, anchorName(index)] as const));
+  const anchors = new Map(
+    Array.map(
+      panes,
+      (pane, index) => [pane.id, isTabbed ? STAGE_ANCHOR : anchorName(index)] as const,
+    ),
+  );
   const info: ReelInfo = {
     model,
     layout,
+    isTabbed,
     toPaneView,
     maybeFocusedId: focusedPaneId(model, layout),
     maybeMark: markOf(model, layout),
     maybeCarriedId: carriedIdOf(model),
   };
 
+  const strip = (): ReadonlyArray<Html> => [
+    h.keyed("div")("gap:start", [
+      h.Class(
+        `reel-gap${
+          isGapMarked(
+            info,
+            Option.map(Array.head(layout), ({ id }) => id),
+          )
+            ? " drop-here"
+            : ""
+        }`,
+      ),
+    ]),
+    ...Array.flatMap(layout, (column, index) => columnView(info, anchors, column, index, h)),
+  ];
+
   return h.div(
-    [h.Class("reel"), h.Role("group"), h.AriaLabel(label), h.DataAttribute("reel", model.id)],
     [
+      h.Class(isTabbed ? "reel tabbed" : "reel"),
+      h.Role("group"),
+      h.AriaLabel(label),
+      h.DataAttribute("reel", model.id),
+    ],
+    [
+      ...(isTabbed ? [tabListView(info, label, toTabLeadView, h)] : []),
       h.div(
         [h.Class("reel-view")],
         [
           h.div(
             [h.Class("reel-track")],
             [
-              h.keyed("div")("gap:start", [
-                h.Class(
-                  `reel-gap${
-                    isGapMarked(
-                      info,
-                      Option.map(Array.head(layout), ({ id }) => id),
-                    )
-                      ? " drop-here"
-                      : ""
-                  }`,
-                ),
-              ]),
-              ...Array.flatMap(layout, (column, index) =>
-                columnView(info, anchors, column, index, h),
-              ),
+              ...(isTabbed
+                ? [
+                    h.div([
+                      h.Class("reel-slot reel-stage"),
+                      h.Style({ "--reel-anchor": STAGE_ANCHOR }),
+                    ]),
+                  ]
+                : strip()),
               paneLayerView(info, panes, anchors, h),
             ],
           ),

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]))),
+      ],
+    }),
   );
 });