@nxgt/material-core 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @nxgt/material-core
 
+## 0.7.0
+
+### Minor Changes
+
+- [#475](https://github.com/softistx/nxgt-material/pull/475) [`2fcfa35`](https://github.com/softistx/nxgt-material/commit/2fcfa35d5bff9d46392247440a82f0bc3638f104) Thanks [@SteveGT96](https://github.com/SteveGT96)! - New `/toast-focus` subpath: `focusOrigin(event, origin)` records where the focus was before it entered a toast, and `handFocusBack(origin)` gives it back there before the toast's action runs (or blurs the toast's control when that element has gone), so a dialog the action opens keeps the focus. `trackToasterOrigin()` records, per `Toaster`, where the focus entered it, so a toast reached from another toast hands the focus back to the same control. `TOASTER_SELECTOR` is `'[data-sonner-toaster]'`. Both libraries' toasts use it ([#473](https://github.com/softistx/nxgt-material/issues/473)).
+
+### Patch Changes
+
+- [#476](https://github.com/softistx/nxgt-material/pull/476) [`464883e`](https://github.com/softistx/nxgt-material/commit/464883e825e4601f17395c9586d0ac01dd392162) Thanks [@SteveGT96](https://github.com/SteveGT96)! - The roadmap names the release that ships the toast action and focus fixes.
+
 ## 0.6.0
 
 ### Minor Changes

package/README.md

@@ -11,7 +11,8 @@ rule, a field's first reachable control (`/focus-control`) and its `aria-describ
 (`/described-by`), the page behind a modal layer made inert
 (`/inert-others`), Escape pressed while an overlay closes
 (`/escape-forward`), the Toaster's guard against a tap's emulated hover
-(`/touch-hover`), a table row's activation, the zod error map's issue
+(`/touch-hover`), the focus a toast's action hands back (`/toast-focus`), a
+table row's activation, the zod error map's issue
 messages (`/zod-issue-messages`), the Vite plugin that bundles pdfkit's
 standard fonts, and the Node-only resolution of those fonts that the Next.js
 helper and the Nuxt module run at build time.
@@ -85,6 +86,7 @@ built-in.
 | `/described-by` | `describedBy` — an `aria-describedby` value from the caller's ids and a field's help and error ids |
 | `/inert-others` | `inertOthers`, `INERT_MARKER` — the rest of the page `inert` behind a modal layer, live regions kept, nested layers counted |
 | `/touch-hover` | `ignoreTouchHover`, `TOASTER_PHONE_QUERY`, `TOASTER_PHONE_POSITION` — keeps a tap from hovering an element, so a toast a finger touched does not stay paused; where the `Toaster` puts toasts on a phone |
+| `/toast-focus` | `focusOrigin`, `handFocusBack`, `trackToasterOrigin`, `TOASTER_SELECTOR` — where the focus was before it entered a toast, and handing it back there before the toast's action runs, so a dialog the action opens keeps the focus |
 | `/zod-issue-messages` | `sizeMessage`, `invalidFormatMessage`, `IssueText` — the translated text of a zod `too_big` / `too_small` and `invalid_format` issue |
 | `/row-activation` | `isRowActivation`, `followRowLink`, `ROW_CONTROL_SELECTOR`, `ROW_LINK_SELECTOR`, `RowClick` — whether a click on a table row follows its link, and following it |
 | `/format-file-size` | `formatFileSize` — a byte count as `'1.5 KB'` |
@@ -613,6 +615,41 @@ It also holds the two constants both libraries' `Toaster` share: `TOASTER_PHONE_
 screen) and `TOASTER_PHONE_POSITION` (`'top-center'`, where toasts go on a phone
 when the caller names no `position`).
 
+### The focus a toast's action hands back: `/toast-focus`
+
+sonner focuses again the control that had the focus before it entered the
+`Toaster` as soon as the focus leaves it, so an action that opened a dialog
+saw the focus pulled back out of the dialog; and a dialog opened from a
+toast's button gave the focus back, once closed, to a button that had gone
+with its toast. Each toast records where the focus came from with
+`focusOrigin(event, origin)` on its `focusin` (focus moving between toasts
+keeps the first origin, or else the one its `Toaster` recorded), and its action calls `handFocusBack(origin)` before
+running: it focuses `origin` (else the `Toaster`'s), or blurs the toast's control when `origin` has
+gone, and does nothing when the focus is not in the `Toaster`
+(`TOASTER_SELECTOR`, `'[data-sonner-toaster]'`). The list item around a
+toast takes the focus first from the keyboard, and no toast hears it:
+`trackToasterOrigin()` (once, when a toast mounts) listens on the document so
+the `Toaster` knows the page control the focus left, and the next toast, which
+never had the focus from the page, still hands it back there.
+
+```ts
+import {
+  focusOrigin,
+  handFocusBack,
+  trackToasterOrigin,
+} from '@nxgt/material-core/toast-focus';
+
+trackToasterOrigin();
+let origin: Element | null = null;
+toastElement.addEventListener('focusin', (event) => {
+  origin = focusOrigin(event, origin);
+});
+actionButton.addEventListener('click', () => {
+  handFocusBack(origin);
+  openDialog();
+});
+```
+
 ### Zod issue messages: `/zod-issue-messages`
 
 The two libraries' zod error maps turn an issue into text in the language

package/dist/lib/toast-focus.d.ts

@@ -0,0 +1,41 @@
+/** The element sonner and vue-sonner render each toast list as. */
+export declare const TOASTER_SELECTOR = "[data-sonner-toaster]";
+/**
+ * Where the focus came from as it entered a toast, for a `focusin` heard on
+ * the toast: the element it left (`relatedTarget`), unless that was already
+ * in a Toaster, as when the focus moves from one toast to the next; then
+ * `origin`, what the toast had recorded so far, is kept, or else what the
+ * Toaster recorded when the focus first entered it (a toast that never had
+ * the focus from outside, as the next one in the list, still has an origin).
+ */
+export declare function focusOrigin(event: Pick<FocusEvent, 'relatedTarget'> & Partial<Pick<FocusEvent, 'target'>>, origin: Element | null): Element | null;
+/**
+ * Records, for each Toaster, where the focus came from as it entered it.
+ * A toast hears the focus only once it reaches one of its own controls, and
+ * with a keyboard it first lands on the list item that wraps the toast
+ * (sonner's and vue-sonner's `li` take `tabindex="0"`), which no toast hears:
+ * this listens on the document, once, so the Toaster knows the page control
+ * the focus left. Call it when a toast mounts; calling it again does nothing.
+ */
+export declare function trackToasterOrigin(doc?: Pick<Document, 'addEventListener'>): void;
+/**
+ * Gives the focus back before a toast's action runs.
+ *
+ * sonner remembers the element focused before the focus entered its Toaster,
+ * and focuses it again the moment the focus leaves (the list's `onBlur`, and
+ * once more when the list unmounts). An action that opens a dialog moves the
+ * focus into the dialog, which counts as leaving: the restore pulled it back
+ * out, and the dialog lost the control it had focused (WCAG 2.4.3).
+ * vue-sonner does not restore (its `blur` does not bubble from the toast's
+ * buttons), so a dialog opened there gave the focus back, once closed, to a
+ * button that had gone with its toast.
+ *
+ * Called first by the action, it focuses `origin` (from {@link focusOrigin}),
+ * else the origin its Toaster recorded, or blurs the toast's control when
+ * neither is left (gone, or inert: `focus()` then silently does nothing).
+ * Only while the focus is in the Toaster: an action run from elsewhere leaves
+ * it alone. sonner then has nothing left to restore; the action moves the focus where it wants, and
+ * a dialog it opens returns the focus to `origin` when it closes.
+ */
+export declare function handFocusBack(origin: Element | null, doc?: Pick<Document, 'activeElement'>): void;
+//# sourceMappingURL=toast-focus.d.ts.map

package/dist/lib/toast-focus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast-focus.d.ts","sourceRoot":"","sources":["../../src/lib/toast-focus.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,eAAO,MAAM,gBAAgB,0BAA0B,CAAC;AAoBxD;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAC1B,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,eAAe,CAAC,GACvC,OAAO,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,EACpC,MAAM,EAAE,OAAO,GAAG,IAAI,GACpB,OAAO,GAAG,IAAI,CAQhB;AAID;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,GAAE,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAY,GAChD,IAAI,CAIN;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAC5B,MAAM,EAAE,OAAO,GAAG,IAAI,EACtB,GAAG,GAAE,IAAI,CAAC,QAAQ,EAAE,eAAe,CAAY,GAC7C,IAAI,CAUN"}

package/dist/lib/toast-focus.js

@@ -0,0 +1,41 @@
+// src/lib/toast-focus.ts
+var TOASTER_SELECTOR = "[data-sonner-toaster]";
+var asFocusable = (value) => typeof value?.closest === "function" && typeof value.focus === "function" ? value : null;
+var toasterOrigins = new WeakMap;
+function focusOrigin(event, origin) {
+  const toaster = asFocusable(event.target)?.closest(TOASTER_SELECTOR);
+  const from = asFocusable(event.relatedTarget);
+  if (from && !from.closest(TOASTER_SELECTOR)) {
+    if (toaster)
+      toasterOrigins.set(toaster, from);
+    return from;
+  }
+  return origin ?? (toaster ? toasterOrigins.get(toaster) ?? null : null);
+}
+var tracked = new WeakSet;
+function trackToasterOrigin(doc = document) {
+  if (tracked.has(doc))
+    return;
+  tracked.add(doc);
+  doc.addEventListener("focusin", (event) => focusOrigin(event, null), true);
+}
+function handFocusBack(origin, doc = document) {
+  const active = asFocusable(doc.activeElement);
+  if (!active?.closest(TOASTER_SELECTOR))
+    return;
+  const toaster = active.closest(TOASTER_SELECTOR);
+  const candidates = [origin, toaster && toasterOrigins.get(toaster)];
+  const target = candidates.map(asFocusable).find((el) => el && el.isConnected !== false);
+  target?.focus({ preventScroll: true });
+  if (asFocusable(doc.activeElement) === active)
+    active.blur();
+}
+export {
+  TOASTER_SELECTOR,
+  focusOrigin,
+  handFocusBack,
+  trackToasterOrigin
+};
+
+//# debugId=0763A78D43B386CF64756E2164756E21
+//# sourceMappingURL=toast-focus.js.map

package/dist/lib/toast-focus.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/toast-focus.ts"],
+  "sourcesContent": [
+    "/** The element sonner and vue-sonner render each toast list as. */\nexport const TOASTER_SELECTOR = '[data-sonner-toaster]';\n\n/** What these helpers read of an element: the DOM's own `HTMLElement` fits. */\ntype Focusable = Pick<HTMLElement, 'closest' | 'focus' | 'blur'> & {\n\treadonly isConnected?: boolean;\n};\n\nconst asFocusable = (value: unknown): Focusable | null =>\n\ttypeof (value as Focusable | null)?.closest === 'function' &&\n\ttypeof (value as Focusable).focus === 'function'\n\t\t? (value as Focusable)\n\t\t: null;\n\n/**\n * Where the focus was before it entered each Toaster, keyed by the Toaster's\n * element: a toast reached from another toast has no origin of its own, and\n * falls back to this one.\n */\nconst toasterOrigins = new WeakMap<Element, Element>();\n\n/**\n * Where the focus came from as it entered a toast, for a `focusin` heard on\n * the toast: the element it left (`relatedTarget`), unless that was already\n * in a Toaster, as when the focus moves from one toast to the next; then\n * `origin`, what the toast had recorded so far, is kept, or else what the\n * Toaster recorded when the focus first entered it (a toast that never had\n * the focus from outside, as the next one in the list, still has an origin).\n */\nexport function focusOrigin(\n\tevent: Pick<FocusEvent, 'relatedTarget'> &\n\t\tPartial<Pick<FocusEvent, 'target'>>,\n\torigin: Element | null,\n): Element | null {\n\tconst toaster = asFocusable(event.target)?.closest(TOASTER_SELECTOR);\n\tconst from = asFocusable(event.relatedTarget);\n\tif (from && !from.closest(TOASTER_SELECTOR)) {\n\t\tif (toaster) toasterOrigins.set(toaster, from as unknown as Element);\n\t\treturn from as unknown as Element;\n\t}\n\treturn origin ?? (toaster ? (toasterOrigins.get(toaster) ?? null) : null);\n}\n\nconst tracked = new WeakSet<object>();\n\n/**\n * Records, for each Toaster, where the focus came from as it entered it.\n * A toast hears the focus only once it reaches one of its own controls, and\n * with a keyboard it first lands on the list item that wraps the toast\n * (sonner's and vue-sonner's `li` take `tabindex=\"0\"`), which no toast hears:\n * this listens on the document, once, so the Toaster knows the page control\n * the focus left. Call it when a toast mounts; calling it again does nothing.\n */\nexport function trackToasterOrigin(\n\tdoc: Pick<Document, 'addEventListener'> = document,\n): void {\n\tif (tracked.has(doc)) return;\n\ttracked.add(doc);\n\tdoc.addEventListener('focusin', (event) => focusOrigin(event, null), true);\n}\n\n/**\n * Gives the focus back before a toast's action runs.\n *\n * sonner remembers the element focused before the focus entered its Toaster,\n * and focuses it again the moment the focus leaves (the list's `onBlur`, and\n * once more when the list unmounts). An action that opens a dialog moves the\n * focus into the dialog, which counts as leaving: the restore pulled it back\n * out, and the dialog lost the control it had focused (WCAG 2.4.3).\n * vue-sonner does not restore (its `blur` does not bubble from the toast's\n * buttons), so a dialog opened there gave the focus back, once closed, to a\n * button that had gone with its toast.\n *\n * Called first by the action, it focuses `origin` (from {@link focusOrigin}),\n * else the origin its Toaster recorded, or blurs the toast's control when\n * neither is left (gone, or inert: `focus()` then silently does nothing).\n * Only while the focus is in the Toaster: an action run from elsewhere leaves\n * it alone. sonner then has nothing left to restore; the action moves the focus where it wants, and\n * a dialog it opens returns the focus to `origin` when it closes.\n */\nexport function handFocusBack(\n\torigin: Element | null,\n\tdoc: Pick<Document, 'activeElement'> = document,\n): void {\n\tconst active = asFocusable(doc.activeElement);\n\tif (!active?.closest(TOASTER_SELECTOR)) return;\n\tconst toaster = active.closest(TOASTER_SELECTOR);\n\tconst candidates = [origin, toaster && toasterOrigins.get(toaster)];\n\tconst target = candidates\n\t\t.map(asFocusable)\n\t\t.find((el) => el && el.isConnected !== false);\n\ttarget?.focus({ preventScroll: true });\n\tif (asFocusable(doc.activeElement) === active) active.blur();\n}\n"
+  ],
+  "mappings": ";AACO,IAAM,mBAAmB;AAOhC,IAAM,cAAc,CAAC,UACpB,OAAQ,OAA4B,YAAY,cAChD,OAAQ,MAAoB,UAAU,aAClC,QACD;AAOJ,IAAM,iBAAiB,IAAI;AAUpB,SAAS,WAAW,CAC1B,OAEA,QACiB;AAAA,EACjB,MAAM,UAAU,YAAY,MAAM,MAAM,GAAG,QAAQ,gBAAgB;AAAA,EACnE,MAAM,OAAO,YAAY,MAAM,aAAa;AAAA,EAC5C,IAAI,QAAQ,CAAC,KAAK,QAAQ,gBAAgB,GAAG;AAAA,IAC5C,IAAI;AAAA,MAAS,eAAe,IAAI,SAAS,IAA0B;AAAA,IACnE,OAAO;AAAA,EACR;AAAA,EACA,OAAO,WAAW,UAAW,eAAe,IAAI,OAAO,KAAK,OAAQ;AAAA;AAGrE,IAAM,UAAU,IAAI;AAUb,SAAS,kBAAkB,CACjC,MAA0C,UACnC;AAAA,EACP,IAAI,QAAQ,IAAI,GAAG;AAAA,IAAG;AAAA,EACtB,QAAQ,IAAI,GAAG;AAAA,EACf,IAAI,iBAAiB,WAAW,CAAC,UAAU,YAAY,OAAO,IAAI,GAAG,IAAI;AAAA;AAsBnE,SAAS,aAAa,CAC5B,QACA,MAAuC,UAChC;AAAA,EACP,MAAM,SAAS,YAAY,IAAI,aAAa;AAAA,EAC5C,IAAI,CAAC,QAAQ,QAAQ,gBAAgB;AAAA,IAAG;AAAA,EACxC,MAAM,UAAU,OAAO,QAAQ,gBAAgB;AAAA,EAC/C,MAAM,aAAa,CAAC,QAAQ,WAAW,eAAe,IAAI,OAAO,CAAC;AAAA,EAClE,MAAM,SAAS,WACb,IAAI,WAAW,EACf,KAAK,CAAC,OAAO,MAAM,GAAG,gBAAgB,KAAK;AAAA,EAC7C,QAAQ,MAAM,EAAE,eAAe,KAAK,CAAC;AAAA,EACrC,IAAI,YAAY,IAAI,aAAa,MAAM;AAAA,IAAQ,OAAO,KAAK;AAAA;",
+  "debugId": "0763A78D43B386CF64756E2164756E21",
+  "names": []
+}

package/docs/roadmap.md

@@ -31,6 +31,9 @@ Nothing in progress right now; see Next.
 
 ## Shipped
 
+- **The focus a toast's action hands back** (`/toast-focus`) — where the
+  focus was before it entered a toast, given back before the action runs, so
+  a dialog the action opens keeps the focus in both libraries. 0.7.0.
 - **A field's first reachable control** (`/focus-control`) — the control of a
   field made of several a user can reach, and a stand-in a form library can
   focus, so both libraries focus the first invalid field. 0.5.0.

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.6.0",
-	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard, the zod issue messages, the date range presets, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
+	"version": "0.7.0",
+	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the zod issue messages, the date range presets, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -113,6 +113,11 @@
 			"import": "./dist/lib/touch-hover.js",
 			"default": "./dist/lib/touch-hover.js"
 		},
+		"./toast-focus": {
+			"types": "./dist/lib/toast-focus.d.ts",
+			"import": "./dist/lib/toast-focus.js",
+			"default": "./dist/lib/toast-focus.js"
+		},
 		"./zod-issue-messages": {
 			"types": "./dist/lib/zod-issue-messages.d.ts",
 			"import": "./dist/lib/zod-issue-messages.js",
@@ -216,6 +221,7 @@
 			"src/lib/escape-forward.ts",
 			"src/lib/described-by.ts",
 			"src/lib/touch-hover.ts",
+			"src/lib/toast-focus.ts",
 			"src/lib/zod-issue-messages.ts",
 			"src/lib/inert-others.ts",
 			"src/lib/row-activation.ts",