@gjermundgaraba-designs/pixel-paper 0.23.0 → 0.25.0

package/dist/src/tips/tips.d.ts

@@ -12,15 +12,18 @@ export declare const TipState: import("foldkit/schema").TaggedUnion<{
     readonly Cold: {};
     readonly Waiting: {
         text: Schema.String;
+        maybeKey: Schema.Option<Schema.String>;
         side: Schema.Literals<readonly ["Top", "Right"]>;
     };
     readonly Shown: {
         text: Schema.String;
+        maybeKey: Schema.Option<Schema.String>;
         side: Schema.Literals<readonly ["Top", "Right"]>;
         trigger: Schema.Literals<readonly ["Pointer", "Focus"]>;
     };
     readonly Leaving: {
         text: Schema.String;
+        maybeKey: Schema.Option<Schema.String>;
         side: Schema.Literals<readonly ["Top", "Right"]>;
         trigger: Schema.Literals<readonly ["Pointer", "Focus"]>;
     };
@@ -36,15 +39,18 @@ export declare const Model: Schema.Struct<{
         readonly Cold: {};
         readonly Waiting: {
             text: Schema.String;
+            maybeKey: Schema.Option<Schema.String>;
             side: Schema.Literals<readonly ["Top", "Right"]>;
         };
         readonly Shown: {
             text: Schema.String;
+            maybeKey: Schema.Option<Schema.String>;
             side: Schema.Literals<readonly ["Top", "Right"]>;
             trigger: Schema.Literals<readonly ["Pointer", "Focus"]>;
         };
         readonly Leaving: {
             text: Schema.String;
+            maybeKey: Schema.Option<Schema.String>;
             side: Schema.Literals<readonly ["Top", "Right"]>;
             trigger: Schema.Literals<readonly ["Pointer", "Focus"]>;
         };
@@ -56,12 +62,14 @@ export type Model = typeof Model.Type;
 export declare const Message: import("foldkit/message").MessageUnion<{
     readonly EnteredTipTarget: {
         text: Schema.String;
+        maybeKey: Schema.Option<Schema.String>;
         side: Schema.Literals<readonly ["Top", "Right"]>;
     };
     readonly LeftTipTarget: {};
     readonly EnteredTip: {};
     readonly FocusedTipTarget: {
         text: Schema.String;
+        maybeKey: Schema.Option<Schema.String>;
         side: Schema.Literals<readonly ["Top", "Right"]>;
     };
     readonly BlurredTipTarget: {};
@@ -136,16 +144,19 @@ export declare const update: (model: Model, message: Message) => Readonly<{
         } | {
             readonly _tag: "Leaving";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Shown";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Waiting";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
         } | {
             readonly _tag: "Warm";
@@ -171,10 +182,12 @@ export declare const update: (model: Model, message: Message) => Readonly<{
     } | {
         readonly _tag: "EnteredTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "FocusedTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "LeftTipTarget";
@@ -210,16 +223,19 @@ export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) =
         } | {
             readonly _tag: "Leaving";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Shown";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Waiting";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
         } | {
             readonly _tag: "Warm";
@@ -244,10 +260,12 @@ export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) =
     } | {
         readonly _tag: "EnteredTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "FocusedTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "LeftTipTarget";
@@ -268,16 +286,19 @@ export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) =
         } | {
             readonly _tag: "Leaving";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Shown";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
             readonly trigger: "Focus" | "Pointer";
         } | {
             readonly _tag: "Waiting";
             readonly text: string;
+            readonly maybeKey: Option.Option<string>;
             readonly side: "Right" | "Top";
         } | {
             readonly _tag: "Warm";
@@ -302,10 +323,12 @@ export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) =
     } | {
         readonly _tag: "EnteredTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "FocusedTipTarget";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "LeftTipTarget";
@@ -321,7 +344,8 @@ export declare const subscriptions: <Prefix extends string>(keyPrefix: Prefix) =
 } extends infer T ? { readonly [Key in keyof T as `${Prefix}${Capitalize<Key>}`]: T[Key]; } : never;
 /**
  * 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
@@ -340,16 +364,19 @@ export declare const view: import("foldkit/submodel").View<{
     } | {
         readonly _tag: "Leaving";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
         readonly trigger: "Focus" | "Pointer";
     } | {
         readonly _tag: "Shown";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
         readonly trigger: "Focus" | "Pointer";
     } | {
         readonly _tag: "Waiting";
         readonly text: string;
+        readonly maybeKey: Option.Option<string>;
         readonly side: "Right" | "Top";
     } | {
         readonly _tag: "Warm";
@@ -374,10 +401,12 @@ export declare const view: import("foldkit/submodel").View<{
 } | {
     readonly _tag: "EnteredTipTarget";
     readonly text: string;
+    readonly maybeKey: Option.Option<string>;
     readonly side: "Right" | "Top";
 } | {
     readonly _tag: "FocusedTipTarget";
     readonly text: string;
+    readonly maybeKey: Option.Option<string>;
     readonly side: "Right" | "Top";
 } | {
     readonly _tag: "LeftTipTarget";

package/dist/src/tips/tips.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../../src/tips/tips.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,MAAM,EAAiB,MAAM,EAAE,MAAM,EAAgB,MAAM,QAAQ,CAAC;AAC9F,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAQ3C,OAAO,KAAK,YAAY,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAW9C,iEAAiE;AACjE,eAAO,MAAM,OAAO,gDAAwC,CAAC;AAC7D,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAK1C;;+FAE+F;AAC/F,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;EAMnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C;sDACsD;AACtD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;EAIhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAItC,uDAAuD;AACvD,eAAO,MAAM,OAAO;;QACE,IAAI;QAAiB,IAAI;;;;;QAGzB,IAAI;QAAiB,IAAI;;;;;;QAIf,OAAO;;;QACR,OAAO;;;QACN,OAAO;;;;EAGrC,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAI1C,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElD,yCAAyC;AACzC,eAAO,MAAM,IAAI,WAAY,UAAU,KAAG,KAIxC,CAAC;AAIH,oDAAoD;AACpD,eAAO,MAAM,EAAE,UAAW,KAAK,KAAG,MAAkB,CAAC;AA2DrD;;;0CAG0C;AAC1C,eAAO,MAAM,OAAO;;;;;;iBAmBlB,CAAC;AAEH,sBAAsB;AACtB,eAAO,MAAM,OAAO;;;;iBAQlB,CAAC;AAEH,mCAAmC;AACnC,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAuEH,6EAA6E;AAC7E,eAAO,MAAM,MAAM,UAAW,KAAK,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDjD,CAAC;AAIL,KAAK,aAAa,GACd,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,GACpC,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,GACjC,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;AAoBnC;gEACgE;AAChE,eAAO,MAAM,kBAAkB,UACtB,MAAM,SACN,YAAY,KAClB,MAAM,CAAC,MAAM,CAAC,aAAa,CAkB7B,CAAC;AAUF;kCACkC;AAClC,eAAO,MAAM,eAAe,UAAW,UAAU,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAQtE,CAAC;AAEJ;;;0CAG0C;AAC1C,eAAO,MAAM,UAAU,UAAW,aAAa,WAAW,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAUxF,CAAC;AAkEF;;;8BAG8B;AAC9B,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mGAC7B,CAAC;AAW1C;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAef,CAAC"}
+{"version":3,"file":"tips.d.ts","sourceRoot":"","sources":["../../../src/tips/tips.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,MAAM,EAIN,MAAM,EACN,MAAM,EAGP,MAAM,QAAQ,CAAC;AAChB,OAAO,KAAK,OAAO,MAAM,iBAAiB,CAAC;AAQ3C,OAAO,KAAK,YAAY,MAAM,sBAAsB,CAAC;AACrD,OAAO,KAAK,KAAK,MAAM,MAAM,gBAAgB,CAAC;AAW9C,iEAAiE;AACjE,eAAO,MAAM,OAAO,gDAAwC,CAAC;AAC7D,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAQ1C;;+FAE+F;AAC/F,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;EAMnB,CAAC;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,IAAI,CAAC;AAE5C;sDACsD;AACtD,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;;;;;;;;EAIhB,CAAC;AACH,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC;AAItC,uDAAuD;AACvD,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;QAQY,OAAO;;;QACR,OAAO;;;QACN,OAAO;;;;EAGrC,CAAC;AACH,MAAM,MAAM,OAAO,GAAG,OAAO,OAAO,CAAC,IAAI,CAAC;AAI1C,2FAA2F;AAC3F,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAElD,yCAAyC;AACzC,eAAO,MAAM,IAAI,WAAY,UAAU,KAAG,KAIxC,CAAC;AAIH,oDAAoD;AACpD,eAAO,MAAM,EAAE,UAAW,KAAK,KAAG,MAAkB,CAAC;AA8DrD;;;0CAG0C;AAC1C,eAAO,MAAM,OAAO;;;;;;iBAmBlB,CAAC;AAEH,sBAAsB;AACtB,eAAO,MAAM,OAAO;;;;iBAQlB,CAAC;AAEH,mCAAmC;AACnC,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAEH,iDAAiD;AACjD,eAAO,MAAM,gBAAgB;;;;;iBAK3B,CAAC;AAEH,+EAA+E;AAC/E,eAAO,MAAM,iBAAiB;;;;;iBAK5B,CAAC;AAyEH,6EAA6E;AAC7E,eAAO,MAAM,MAAM,UAAW,KAAK,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAmDjD,CAAC;AAIL,KAAK,aAAa,GACd,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,GACpC,OAAO,OAAO,CAAC,aAAa,CAAC,IAAI,GACjC,OAAO,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC;AA0BnC;gEACgE;AAChE,eAAO,MAAM,kBAAkB,UACtB,MAAM,SACN,YAAY,KAClB,MAAM,CAAC,MAAM,CAAC,aAAa,CAkB7B,CAAC;AAUF;kCACkC;AAClC,eAAO,MAAM,eAAe,UAAW,UAAU,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAQtE,CAAC;AAEJ;;;0CAG0C;AAC1C,eAAO,MAAM,UAAU,UAAW,aAAa,WAAW,OAAO,KAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAUxF,CAAC;AAoEF;;;8BAG8B;AAC9B,eAAO,MAAM,aAAa,GAAI,MAAM,SAAS,MAAM,aAAa,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mGAC7B,CAAC;AAW1C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;QAqBf,CAAC"}

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.25.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),
     ],