@gjermundgaraba-designs/pixel-paper 0.22.2 → 0.24.0

package/src/tips/tips.ts

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

package/src/toast/index.ts

@@ -13,6 +13,6 @@ export {
   update,
   view,
 } from "./toast.ts";
-export type { InitConfig, ShowConfig, ShowReturn } from "./toast.ts";
+export type { InitConfig, ShowConfig } from "./toast.ts";
 export type { Action, Tone } from "./stack.ts";
 export { Focus } from "../focus/focus.ts";

package/src/toast/toast.ts

@@ -295,7 +295,7 @@ const oldestCalm = (model: Model): Option.Option<Stack.Entry> => {
 
 /** What `show` returns: the next Model and Commands, and the new slip's id, to take it back
  *  with `dismiss`. */
-export type ShowReturn = Update.Return<Model, Message> & Readonly<{ entryId: string }>;
+type ShowReturn = Update.Return<Model, Message> & Readonly<{ entryId: string }>;
 
 const spoken = (config: ShowConfig): string =>
   config.body === undefined ? `${config.title}.` : `${config.title}. ${config.body}`;
@@ -350,17 +350,11 @@ export const dismiss = (model: Model, entryId: string): StepReturn =>
 
 // VIEW
 
-const TONE_CLASS: Record<Tone, string> = {
-  Ok: "notice toast ok",
-  Error: "notice toast error",
-  Quiet: "notice toast quiet",
-};
-
 const slipView = (entry: Stack.Entry, h: HtmlBuilder<Message>): Html => {
   const { tone, title, maybeBody, maybeAction } = entry.payload;
 
   return h.div(
-    [h.Class(TONE_CLASS[tone])],
+    [h.Class(`notice toast${Notice.TONE_CLASS[tone]}`)],
     [
       Notice.toneGlyphView({ tone }, h),
       h.div([], [h.strong([], [title]), ...Option.toArray(maybeBody)]),

package/src/tokens.css

@@ -81,6 +81,11 @@
     conic-gradient(at 1px 1px, #0000 75%, var(--dither-dot) 0) 0 0 / 4px 4px,
     conic-gradient(at 1px 1px, #0000 75%, var(--dither-dot) 0) 2px 2px / 4px 4px, var(--dither-base);
 
+  /* ---------- colour: fades ---------- */
+  --fade-on-ink: 0.75; /* what prints muted on paper, printed in paper on an inverted fill */
+  --fade-held: 0.6; /* a held control on an ink title bar */
+  --fade-dragged: 0.4; /* a held item, dimmed in place while its copy follows the pointer */
+
   /* ---------- type: three families ---------- */
   --font-px: "Departure Mono", ui-monospace, Menlo, Monaco, monospace;
   --font-body: system-ui, "Helvetica Neue", Helvetica, Arial, sans-serif;
@@ -122,6 +127,7 @@
   --deck: 1160px; /* the widest a deck of panels runs */
   --rail: 272px; /* the column of panels beside a deck, until the reader sizes it */
   --rail-drawer: 320px; /* the rail as a drawer, whatever width the reader gave it */
+  --rail-folded: 64px; /* the rail folded to its first panel's bar, stood on end */
 
   /* ---------- space: between components (Stack, Group, Wrap) ---------- */
   --space-s: 8px; /* things in one line: buttons, chips, a glyph and its word */
@@ -147,6 +153,7 @@
 
   /* ---------- the bench: a page whose work is the window ---------- */
   --bench-work-min: 152px; /* the least of its height the work keeps: a 120px pane, 16px gutters */
+  --bench-head-min: 64px; /* the least of its head a short window keeps: its padding and a small button */
 
   /* ---------- charts ---------- */
   --chart-plot: 160px; /* a line chart's plot, between its top line and its axis */

package/src/toolbar/toolbar.ts

@@ -4,7 +4,6 @@ import type { Html, HtmlBuilder } from "foldkit/html";
 import { defineMessageUnion } from "foldkit/message";
 import * as Mount from "foldkit/mount";
 
-import type { Attributes } from "../attributes/attributes.ts";
 import { isPlain } from "../keys/keys.ts";
 
 // MODEL
@@ -172,8 +171,6 @@ export type ViewConfig<ParentMessage> = Readonly<{
    *  Scene, resolve the Mount by name with the lifted Message:
    *  `Scene.Mount.resolve({ name: Toolbar.BindToolKeys.name }, toParentMessage(Toolbar.Message.MovedToolFocus({ move })))`. */
   toParentMessage: (message: Message) => ParentMessage;
-  /** Further attributes for the toolbar, never a class. */
-  attributes?: Attributes<ParentMessage>;
 }>;
 
 /** A strip of tools that is one stop for Tab (`role="toolbar"`, named by its label, with its
@@ -189,12 +186,10 @@ export const view = <ParentMessage>(
     orientation = "Horizontal",
     isFloating = false,
     toParentMessage,
-    attributes = [],
   } = config;
 
   return h.div(
     [
-      ...attributes,
       h.Role("toolbar"),
       h.AriaLabel(label),
       h.AriaOrientation(orientation === "Vertical" ? "vertical" : "horizontal"),

package/dist/src/inlineInput/inline.d.ts

@@ -1,6 +0,0 @@
-import { Option } from "effect";
-/** What Enter or leaving an inline field writes: the draft trimmed, or none (an untouched
- *  draft, so an edit made elsewhere to `value` is never overwritten; an empty one; or the
- *  text it replaces). */
-export declare const toWrite: (maybeDraft: Option.Option<string>, value: string) => Option.Option<string>;
-//# sourceMappingURL=inline.d.ts.map

package/dist/src/inlineInput/inline.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"inline.d.ts","sourceRoot":"","sources":["../../../src/inlineInput/inline.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAgB,MAAM,QAAQ,CAAC;AAI9C;;yBAEyB;AACzB,eAAO,MAAM,OAAO,eAAgB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAK5F,CAAC"}

package/dist/src/inlineInput/inline.js

@@ -1,7 +0,0 @@
-import { brandViewResult as __foldkitBrandViewResult } from 'foldkit/brand'
-import { Option, String, pipe } from "effect";
-// RULES
-/** What Enter or leaving an inline field writes: the draft trimmed, or none (an untouched
- *  draft, so an edit made elsewhere to `value` is never overwritten; an empty one; or the
- *  text it replaces). */
-export const toWrite = (maybeDraft, value) => __foldkitBrandViewResult((pipe(maybeDraft, Option.map(String.trim), Option.filter((text) => __foldkitBrandViewResult((String.isNonEmpty(text) && text !== value), "@gjermundgaraba-designs/pixel-paper/src/inlineInput/inline.js#anonymous")))), "@gjermundgaraba-designs/pixel-paper/src/inlineInput/inline.js#toWrite");

package/src/inlineInput/inline.ts

@@ -1,13 +0,0 @@
-import { Option, String, pipe } from "effect";
-
-// RULES
-
-/** What Enter or leaving an inline field writes: the draft trimmed, or none (an untouched
- *  draft, so an edit made elsewhere to `value` is never overwritten; an empty one; or the
- *  text it replaces). */
-export const toWrite = (maybeDraft: Option.Option<string>, value: string): Option.Option<string> =>
-  pipe(
-    maybeDraft,
-    Option.map(String.trim),
-    Option.filter((text) => String.isNonEmpty(text) && text !== value),
-  );