@gjermundgaraba-designs/pixel-paper 0.23.0 → 0.24.0

package/dist/src/tips/tips.js

@@ -1,5 +1,5 @@
 import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
-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 { defineMessageUnion } from "foldkit/message";
@@ -15,7 +15,9 @@ import { prefixKeys } from "../subscription/prefixKeys.js";
 const Side = Schema.Literals(["Top", "Right"]);
 /** What brought the tip: a resting pointer or keyboard focus. */
 export const Trigger = Schema.Literals(["Pointer", "Focus"]);
-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 };
 const ShownWords = { ...Words, trigger: Trigger };
 /** Where the page's tip is. `Cold`: none lately. `Waiting`: a pointer rests on a control, for
  *  a moment first. `Shown`. `Leaving`: the pointer left, with a moment to cross onto the tip.
@@ -37,10 +39,10 @@ export const Model = Schema.Struct({
 // MESSAGE
 /** 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: {},
@@ -70,6 +72,8 @@ const GRACE = Duration.millis(120);
 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, text) => __foldkitBrandViewResult((element.isConnected && element.getAttribute(TIP_ATTRIBUTE) === text), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#hasText");
 /** The control a tip belongs to, found when it opens: the innermost hovered element with
@@ -117,9 +121,10 @@ export const WaitBeforeCooling = Command.define("WaitBeforeCooling", {
     messages: [Message.CompletedWaitBeforeCooling],
     execute: ({ version }) => __foldkitBrandViewResult((Effect.sleep(WARMTH).pipe(Effect.as(Message.CompletedWaitBeforeCooling({ version })))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#execute~5"),
 });
-const show = (model, text, side, trigger) => (__foldkitBrandViewResult(({
-    model: modifyFields(model, { state: () => __foldkitBrandViewResult((TipState.Shown({ text, side, trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state") }),
-    commands: [ShowTip({ tipId: model.id, text, trigger })],
+const wordsOf = ({ text, maybeKey, side }) => (__foldkitBrandViewResult(({ text, maybeKey, side }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#wordsOf"));
+const show = (model, words, trigger) => (__foldkitBrandViewResult(({
+    model: modifyFields(model, { state: () => __foldkitBrandViewResult((TipState.Shown({ ...wordsOf(words), trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state") }),
+    commands: [ShowTip({ tipId: model.id, text: words.text, trigger })],
 }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#show"));
 const hide = (model) => {
     const nextVersion = Number.increment(model.version);
@@ -128,12 +133,12 @@ const hide = (model) => {
         commands: [HideTip({ tipId: model.id }), WaitBeforeCooling({ version: nextVersion })],
     }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#hide");
 };
-const wait = (model, text, side) => {
+const wait = (model, words) => {
     const nextVersion = Number.increment(model.version);
     return __foldkitBrandViewResult(({
         model: modifyFields(model, {
             version: () => __foldkitBrandViewResult((nextVersion), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#version~2"),
-            state: () => __foldkitBrandViewResult((TipState.Waiting({ text, side })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~3"),
+            state: () => __foldkitBrandViewResult((TipState.Waiting(wordsOf(words))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~3"),
         }),
         commands: [WaitBeforeShowing({ version: nextVersion })],
     }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#wait");
@@ -143,7 +148,7 @@ const leave = (model, shown) => {
     return __foldkitBrandViewResult(({
         model: modifyFields(model, {
             version: () => __foldkitBrandViewResult((nextVersion), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#version~3"),
-            state: () => __foldkitBrandViewResult((TipState.Leaving({ text: shown.text, side: shown.side, trigger: shown.trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~4"),
+            state: () => __foldkitBrandViewResult((TipState.Leaving({ ...wordsOf(shown), trigger: shown.trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~4"),
         }),
         commands: [WaitBeforeHiding({ version: nextVersion })],
     }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#leave");
@@ -159,47 +164,55 @@ const dismiss = (model) => __foldkitBrandViewResult((TipState.match(model.state,
     Leaving: () => __foldkitBrandViewResult((hide(model)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Leaving"),
     Warm: () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Warm")),
 })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#dismiss");
-const entered = (model, text, side) => __foldkitBrandViewResult((TipState.match(model.state, {
-    Cold: () => __foldkitBrandViewResult((wait(model, text, side)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Cold~2"),
-    Waiting: (waiting) => (__foldkitBrandViewResult((waiting.text === text ? { model } : wait(model, text, side)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Waiting~2")),
-    Shown: (shown) => (__foldkitBrandViewResult((shown.text === text ? { model } : show(model, text, side, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Shown~2")),
-    Leaving: (leaving) => __foldkitBrandViewResult((leaving.text === text
+const entered = (model, words) => __foldkitBrandViewResult((TipState.match(model.state, {
+    Cold: () => __foldkitBrandViewResult((wait(model, words)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Cold~2"),
+    Waiting: (waiting) => (__foldkitBrandViewResult((waiting.text === words.text ? { model } : wait(model, words)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Waiting~2")),
+    Shown: (shown) => (__foldkitBrandViewResult((shown.text === words.text ? { model } : show(model, words, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Shown~2")),
+    Leaving: (leaving) => __foldkitBrandViewResult((leaving.text === words.text
         ? {
             model: modifyFields(model, {
-                state: () => __foldkitBrandViewResult((TipState.Shown({ text, side, trigger: leaving.trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~6"),
+                state: () => __foldkitBrandViewResult((TipState.Shown({ ...wordsOf(words), trigger: leaving.trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~6"),
             }),
         }
-        : show(model, text, side, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Leaving~2"),
-    Warm: () => __foldkitBrandViewResult((show(model, text, side, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Warm~2"),
+        : show(model, words, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Leaving~2"),
+    Warm: () => __foldkitBrandViewResult((show(model, words, "Pointer")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Warm~2"),
 })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#entered");
 /** Processes a tip layer Message and returns the next Model and Commands. */
 export const update = (model, message) => __foldkitBrandViewResult((Message.match(message, {
-    EnteredTipTarget: ({ text, side }) => __foldkitBrandViewResult((entered(model, text, side)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#EnteredTipTarget"),
+    EnteredTipTarget: (words) => __foldkitBrandViewResult((entered(model, wordsOf(words))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#EnteredTipTarget"),
     LeftTipTarget: () => __foldkitBrandViewResult((TipState.matchOrElse(model.state, {
         Waiting: () => __foldkitBrandViewResult((cool(model)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Waiting~3"),
         Shown: (shown) => (__foldkitBrandViewResult((shown.trigger === "Pointer" ? leave(model, shown) : { model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Shown~3")),
     }, () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~11")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#LeftTipTarget"),
     EnteredTip: () => __foldkitBrandViewResult((TipState.matchOrElse(model.state, {
-        Leaving: ({ text, side, trigger }) => (__foldkitBrandViewResult(({
-            model: modifyFields(model, { state: () => __foldkitBrandViewResult((TipState.Shown({ text, side, trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~7") }),
+        Leaving: (leaving) => (__foldkitBrandViewResult(({
+            model: modifyFields(model, {
+                state: () => __foldkitBrandViewResult((TipState.Shown({ ...wordsOf(leaving), trigger: leaving.trigger })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#state~7"),
+            }),
         }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Leaving~3")),
     }, () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~12")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#EnteredTip"),
-    FocusedTipTarget: ({ text, side }) => __foldkitBrandViewResult((show(model, text, side, "Focus")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#FocusedTipTarget"),
+    FocusedTipTarget: (words) => __foldkitBrandViewResult((show(model, wordsOf(words), "Focus")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#FocusedTipTarget"),
     BlurredTipTarget: () => __foldkitBrandViewResult((dismiss(model)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#BlurredTipTarget"),
     PressedPointer: () => __foldkitBrandViewResult((dismiss(model)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#PressedPointer"),
     PressedKey: () => __foldkitBrandViewResult((dismiss(model)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#PressedKey"),
     CompletedWaitBeforeShowing: ({ version }) => __foldkitBrandViewResult((TipState.matchOrElse(model.state, {
-        Waiting: ({ text, side }) => __foldkitBrandViewResult((model.version === version ? show(model, text, side, "Pointer") : { model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Waiting~4"),
+        Waiting: (waiting) => __foldkitBrandViewResult((model.version === version ? show(model, wordsOf(waiting), "Pointer") : { model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Waiting~4"),
     }, () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~13")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#CompletedWaitBeforeShowing"),
     CompletedWaitBeforeHiding: ({ version }) => __foldkitBrandViewResult((TipState.matchOrElse(model.state, { Leaving: () => (__foldkitBrandViewResult((model.version === version ? hide(model) : { model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Leaving~4")) }, () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~14")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#CompletedWaitBeforeHiding"),
     CompletedWaitBeforeCooling: ({ version }) => __foldkitBrandViewResult((TipState.matchOrElse(model.state, { Warm: () => (__foldkitBrandViewResult((model.version === version ? cool(model) : { model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#Warm~3")) }, () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~15")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#CompletedWaitBeforeCooling"),
     CompletedShowTip: () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#CompletedShowTip")),
     CompletedHideTip: () => (__foldkitBrandViewResult(({ model }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#CompletedHideTip")),
 })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#update");
-const sideOf = (element) => __foldkitBrandViewResult((element.closest('[aria-orientation="vertical"]') === null ? "Top" : "Right"), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#sideOf");
+/** 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) => __foldkitBrandViewResult((element.closest('[aria-orientation="vertical"]') === null &&
+    !getComputedStyle(element).writingMode.startsWith("vertical")
+    ? "Top"
+    : "Right"), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#sideOf");
 const tipTargetOf = (target) => __foldkitBrandViewResult((pipe(Option.liftPredicate(target, (node) => __foldkitBrandViewResult((node instanceof Element), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~16")), Option.flatMap((element) => __foldkitBrandViewResult((Option.fromNullishOr(element.closest(TIP_SELECTOR))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~17")), Option.flatMap((element) => __foldkitBrandViewResult((Option.map(Option.fromNullishOr(element.getAttribute(TIP_ATTRIBUTE)), (text) => (__foldkitBrandViewResult(({
     element,
     text,
+    maybeKey: Option.fromNullishOr(element.getAttribute(TIP_KEY_ATTRIBUTE)),
     side: sideOf(element),
 }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~19")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~18")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#tipTargetOf");
 /** What a pointer arriving over `target` means for the tip: over a control with a tip, over
@@ -214,12 +227,12 @@ export const pointerOverMessage = (tipId, event) => {
     }
     return __foldkitBrandViewResult((Option.some(Option.match(tipTargetOf(event.target), {
         onNone: () => __foldkitBrandViewResult((Message.LeftTipTarget()), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#onNone"),
-        onSome: ({ text, side }) => __foldkitBrandViewResult((Message.EnteredTipTarget({ text, side })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#onSome"),
+        onSome: (target) => __foldkitBrandViewResult((Message.EnteredTipTarget(wordsOf(target))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#onSome"),
     }))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#pointerOverMessage");
 };
 /** What focus arriving on `target` means for the tip: keyboard focus (`:focus-visible`) on a
  *  control with a tip shows it; any other focus says nothing. */
-const focusInMessage = (event) => __foldkitBrandViewResult((Option.map(Option.filter(tipTargetOf(event.target), ({ element }) => __foldkitBrandViewResult((element.matches(":focus-visible")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~20")), ({ text, side }) => __foldkitBrandViewResult((Message.FocusedTipTarget({ text, side })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~21"))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#focusInMessage");
+const focusInMessage = (event) => __foldkitBrandViewResult((Option.map(Option.filter(tipTargetOf(event.target), ({ element }) => __foldkitBrandViewResult((element.matches(":focus-visible")), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~20")), (target) => __foldkitBrandViewResult((Message.FocusedTipTarget(wordsOf(target))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~21"))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#focusInMessage");
 /** Focus leaving a control with a tip, not into a part of itself, closes the tip (and
  *  cancels one still waiting). */
 export const focusOutMessage = (event) => __foldkitBrandViewResult((Option.map(Option.filter(tipTargetOf(event.target), ({ element }) => __foldkitBrandViewResult((!(event.relatedTarget instanceof Node && element.contains(event.relatedTarget))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~22")), () => __foldkitBrandViewResult((Message.BlurredTipTarget()), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~23"))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#focusOutMessage");
@@ -244,7 +257,9 @@ const pointerOverChanges = (tipId) => __foldkitBrandViewResult((Dom.streamFromEv
 }).pipe(Stream.changesWith((previous, next) => __foldkitBrandViewResult((previous._tag === next._tag && sameWords(previous, next)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~24")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#pointerOverChanges");
 const sameWords = (previous, next) => __foldkitBrandViewResult((previous._tag !== "EnteredTipTarget" ||
     next._tag !== "EnteredTipTarget" ||
-    (previous.text === next.text && previous.side === next.side)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#sameWords");
+    (previous.text === next.text &&
+        previous.side === next.side &&
+        Equal.equals(previous.maybeKey, next.maybeKey))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#sameWords");
 const tipSubscriptions = Subscription.make()((entry) => (__foldkitBrandViewResult(({
     pointerAndFocus: entry({ tipId: Schema.String }, {
         modelToDependencies: (model) => (__foldkitBrandViewResult(({ tipId: model.id }), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#modelToDependencies")),
@@ -286,10 +301,11 @@ const tipSubscriptions = Subscription.make()((entry) => (__foldkitBrandViewResul
  *  only while a tip shows. */
 export const subscriptions = (keyPrefix) => __foldkitBrandViewResult((prefixKeys(keyPrefix, tipSubscriptions)), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#subscriptions");
 // VIEW
-const wordsOf = (model) => __foldkitBrandViewResult((Match.value(model.state).pipe(Match.withReturnType(), Match.tag("Waiting", "Shown", "Leaving", ({ text, side }) => __foldkitBrandViewResult((Option.some({ text, side })), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~26")), Match.orElse(() => __foldkitBrandViewResult((Option.none()), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~27")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#wordsOf");
+const maybeWordsOf = (model) => __foldkitBrandViewResult((Match.value(model.state).pipe(Match.withReturnType(), Match.tag("Waiting", "Shown", "Leaving", (words) => __foldkitBrandViewResult((Option.some(wordsOf(words))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~26")), Match.orElse(() => __foldkitBrandViewResult((Option.none()), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~27")))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#maybeWordsOf");
 /**
  * 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
@@ -301,7 +317,7 @@ const wordsOf = (model) => __foldkitBrandViewResult((Match.value(model.state).pi
  * accessibility tree, and any control takes one by carrying `data-tip`.
  */
 export const view = defineView((model, h) => {
-    const maybeWords = wordsOf(model);
+    const maybeWords = maybeWordsOf(model);
     return __foldkitBrandViewResult((h.div([
         h.Id(model.id),
         h.Popover("manual"),
@@ -310,5 +326,11 @@ export const view = defineView((model, h) => {
         ...(Option.exists(maybeWords, ({ side }) => __foldkitBrandViewResult((side === "Right"), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~29"))
             ? [h.DataAttribute("side", "right")]
             : []),
-    ], Option.isSome(maybeWords) ? [maybeWords.value.text] : [])), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~28");
+    ], Option.match(maybeWords, {
+        onNone: () => __foldkitBrandViewResult(([]), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#onNone~3"),
+        onSome: ({ text, maybeKey }) => __foldkitBrandViewResult(([
+            text,
+            ...Array.fromOption(Option.map(maybeKey, (key) => __foldkitBrandViewResult((h.kbd([h.Class("key-hint")], [key])), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~30"))),
+        ]), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#onSome~3"),
+    }))), "@gjermundgaraba-designs/pixel-paper/src/tips/tips.js#anonymous~28");
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba-designs/pixel-paper",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/iconButton/iconButton.ts

@@ -2,8 +2,10 @@ import { Button as UiButton } from "@foldkit/ui";
 import type { Html, HtmlBuilder } from "foldkit/html";
 
 import type { Attributes } from "../attributes/attributes.ts";
+import type { KeyHintConfig } from "../button/button.ts";
 import * as Glyph from "../glyph/glyph.ts";
 import type { GlyphName } from "../glyph/glyphs.ts";
+import { keyLabel } from "../keyHint/keyLabel.ts";
 
 // VIEW
 
@@ -17,13 +19,25 @@ export type ViewConfig<Message> = Readonly<{
   isQuiet?: boolean;
   /** Unavailable but focusable (`aria-disabled`), as in `@foldkit/ui`. */
   isDisabled?: boolean;
+  /** The key that does the same, printed in the tip after the label (`data-tip-key`): the
+   *  button has no words to print it beside. */
+  keyHint?: KeyHintConfig;
   /** Further attributes for the `<button>`, never a class. */
   attributes?: Attributes<Message>;
 }>;
 
-/** A bare glyph button, 24px square. Its label is its accessible name and its tip. */
+/** A bare glyph button, 24px square. Its label is its accessible name and its tip, and its
+ *  key, where it has one, prints in the tip after the label. */
 export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Message>): Html => {
-  const { glyph, label, onClick, isQuiet = false, isDisabled = false, attributes = [] } = config;
+  const {
+    glyph,
+    label,
+    onClick,
+    isQuiet = false,
+    isDisabled = false,
+    keyHint,
+    attributes = [],
+  } = config;
 
   return UiButton.view(
     {
@@ -36,6 +50,9 @@ export const view = <Message>(config: ViewConfig<Message>, h: HtmlBuilder<Messag
             ...groups.button,
             h.AriaLabel(label),
             h.DataAttribute("tip", label),
+            ...(keyHint === undefined
+              ? []
+              : [h.DataAttribute("tip-key", keyLabel(keyHint.keys, keyHint.platform))]),
             h.Class(isQuiet ? "iconbtn quiet" : "iconbtn"),
           ],
           [Glyph.view({ name: glyph }, h)],

package/src/panel/panel.ts

@@ -26,6 +26,9 @@ export type ViewConfig = Readonly<{
   /** Small Buttons and IconButtons at the title bar's right end, after the meta. On the ink
    *  bar they print in paper, flat, and ring in their own colour inside their edge. */
   actions?: ReadonlyArray<Html | string>;
+  /** A strip on the head tint between the title bar and the body, for a field that picks what
+   *  the body shows (an area over its tasks). Its labels print in on-head. */
+  shelf?: ReadonlyArray<Html | string>;
   body: ReadonlyArray<Html | string>;
   /** A ruled foot under the body: a note line, then actions pushed right. */
   foot?: ReadonlyArray<Html | string>;
@@ -46,6 +49,7 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
     lead = [],
     meta,
     actions = [],
+    shelf = [],
     body,
     foot = [],
     isFlush = false,
@@ -68,6 +72,7 @@ export const view = <Message>(config: ViewConfig, h: HtmlBuilder<Message>): Html
           ...slotView("span", "panel-acts", actions, h),
         ],
       ),
+      ...slotView("div", "panel-shelf", shelf, h),
       ...(isFlush ? body : [h.div([h.Class("panel-body")], body)]),
       ...slotView("div", "panel-foot", foot, h),
     ],

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,9 +5081,45 @@ 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
    margin and never over the rail's own scrollbar, and beside the rail rather than in it (the
    rail scrolls, and its drawer's first Tab stop is its first control). It shows itself as a
@@ -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 {
@@ -5842,4 +5952,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";