foldkit 0.82.8 → 0.82.9

package/dist/task/dom.d.ts

@@ -1,7 +1,17 @@
 import { Effect } from 'effect';
 import { ElementNotFound } from './error.js';
 /**
- * Focuses an element matching the given selector.
+ * Focuses an element matching the given selector after the next render has
+ * committed.
+ *
+ * For focus that should happen because an element just appeared (an input
+ * mounting, a dialog opening), prefer `OnMount` with a `Mount.define`'d
+ * action — focus is then a consequence of the element's lifecycle and runs
+ * synchronously inside the snabbdom insert hook with no race window.
+ * Reserve `Task.focus` for the post-Message case (returning focus to a
+ * trigger button after a popover closes, refocusing on blur, keyboard
+ * navigation across a stable layout).
+ *
  * Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.
  *
  * @example

package/dist/task/dom.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/task/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAMP,MAAM,QAAQ,CAAA;AAEf,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmB5C;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAQxE,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAgDlC,CAAA;AAuBJ;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAclC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAQlC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAQlC,CAAA;AAEJ,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,EAChB,WAAW,cAAc,KACxB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAqClC,CAAA"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/task/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAMP,MAAM,QAAQ,CAAA;AAEf,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAsC5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,KAAK,GAAI,UAAU,MAAM,KAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKxE,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,SAAS,GACpB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAgDlC,CAAA;AAuBJ;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAclC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ,0EAA0E;AAC1E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,CAAA;AAEhD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,EAChB,WAAW,cAAc,KACxB,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAiClC,CAAA"}

package/dist/task/dom.js

@@ -11,8 +11,32 @@ const FOCUSABLE_SELECTOR = Array.join([
     'textarea:not([disabled]):not([tabindex="-1"])',
     '[tabindex]:not([tabindex="-1"])',
 ], ', ');
+// NOTE: DOM tasks await one rAF before walking the tree. The runtime defers
+// renders to the next animation frame and forks Commands on the microtask
+// queue, so without this wait a Task that runs immediately after a dirtying
+// Message would query the DOM before the matching VDOM patch has committed.
+const awaitNextFrame = Effect.callback(resume => {
+    const handle = requestAnimationFrame(() => resume(Effect.void));
+    return Effect.sync(() => cancelAnimationFrame(handle));
+});
+const queryHTMLElement = (selector) => Effect.suspend(() => {
+    const element = document.querySelector(selector);
+    return element instanceof HTMLElement
+        ? Effect.succeed(element)
+        : Effect.fail(new ElementNotFound({ selector }));
+});
 /**
- * Focuses an element matching the given selector.
+ * Focuses an element matching the given selector after the next render has
+ * committed.
+ *
+ * For focus that should happen because an element just appeared (an input
+ * mounting, a dialog opening), prefer `OnMount` with a `Mount.define`'d
+ * action — focus is then a consequence of the element's lifecycle and runs
+ * synchronously inside the snabbdom insert hook with no race window.
+ * Reserve `Task.focus` for the post-Message case (returning focus to a
+ * trigger button after a popover closes, refocusing on blur, keyboard
+ * navigation across a stable layout).
+ *
  * Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.
  *
  * @example
@@ -20,13 +44,10 @@ const FOCUSABLE_SELECTOR = Array.join([
  * Task.focus('#email-input').pipe(Effect.ignore, Effect.as(CompletedFocusInput()))
  * ```
  */
-export const focus = (selector) => Effect.suspend(() => {
-    const element = document.querySelector(selector);
-    if (element instanceof HTMLElement) {
-        element.focus();
-        return Effect.void;
-    }
-    return Effect.fail(new ElementNotFound({ selector }));
+export const focus = (selector) => Effect.gen(function* () {
+    yield* awaitNextFrame;
+    const element = yield* queryHTMLElement(selector);
+    element.focus();
 });
 /**
  * Opens a dialog element using `show()` with high z-index, focus trapping,
@@ -43,10 +64,11 @@ export const focus = (selector) => Effect.suspend(() => {
  * Task.showModal('#my-dialog', { focusSelector: '#search-input' }).pipe(Effect.ignore, Effect.as(CompletedShowDialog()))
  * ```
  */
-export const showModal = (selector, options) => Effect.suspend(() => {
+export const showModal = (selector, options) => Effect.gen(function* () {
+    yield* awaitNextFrame;
     const element = document.querySelector(selector);
     if (!(element instanceof HTMLDialogElement)) {
-        return Effect.fail(new ElementNotFound({ selector }));
+        return yield* Effect.fail(new ElementNotFound({ selector }));
     }
     element.style.position = 'fixed';
     element.style.inset = '0';
@@ -75,7 +97,6 @@ export const showModal = (selector, options) => Effect.suspend(() => {
             focusTarget.focus();
         }
     }
-    return Effect.void;
 });
 const trapFocusWithinDialog = (event, dialog) => {
     const focusable = Array.fromIterable(dialog.querySelectorAll(FOCUSABLE_SELECTOR));
@@ -125,13 +146,10 @@ export const closeModal = (selector) => Effect.suspend(() => {
  * Task.clickElement('#menu-item-2').pipe(Effect.ignore, Effect.as(CompletedClickItem()))
  * ```
  */
-export const clickElement = (selector) => Effect.suspend(() => {
-    const element = document.querySelector(selector);
-    if (element instanceof HTMLElement) {
-        element.click();
-        return Effect.void;
-    }
-    return Effect.fail(new ElementNotFound({ selector }));
+export const clickElement = (selector) => Effect.gen(function* () {
+    yield* awaitNextFrame;
+    const element = yield* queryHTMLElement(selector);
+    element.click();
 });
 /**
  * Scrolls an element into view by selector using `{ block: 'nearest' }`.
@@ -142,13 +160,10 @@ export const clickElement = (selector) => Effect.suspend(() => {
  * Task.scrollIntoView('#active-item').pipe(Effect.ignore, Effect.as(CompletedScrollIntoView()))
  * ```
  */
-export const scrollIntoView = (selector) => Effect.suspend(() => {
-    const element = document.querySelector(selector);
-    if (element instanceof HTMLElement) {
-        element.scrollIntoView({ block: 'nearest' });
-        return Effect.void;
-    }
-    return Effect.fail(new ElementNotFound({ selector }));
+export const scrollIntoView = (selector) => Effect.gen(function* () {
+    yield* awaitNextFrame;
+    const element = yield* queryHTMLElement(selector);
+    element.scrollIntoView({ block: 'nearest' });
 });
 /**
  * Focuses the next or previous focusable element in the document relative to the element matching the given selector.
@@ -159,20 +174,17 @@ export const scrollIntoView = (selector) => Effect.suspend(() => {
  * Task.advanceFocus('#menu-button', 'Next').pipe(Effect.ignore, Effect.as(CompletedAdvanceFocus()))
  * ```
  */
-export const advanceFocus = (selector, direction) => Effect.suspend(() => {
-    const reference = document.querySelector(selector);
-    if (!(reference instanceof HTMLElement)) {
-        return Effect.fail(new ElementNotFound({ selector }));
-    }
+export const advanceFocus = (selector, direction) => Effect.gen(function* () {
+    yield* awaitNextFrame;
+    const reference = yield* queryHTMLElement(selector);
     const focusableElements = Array.fromIterable(document.querySelectorAll(FOCUSABLE_SELECTOR));
     const referenceElementIndex = Array.findFirstIndex(focusableElements, Equal.equals(reference));
     if (Option.isNone(referenceElementIndex)) {
-        return Effect.fail(new ElementNotFound({ selector }));
+        return yield* Effect.fail(new ElementNotFound({ selector }));
     }
     const offsetReferenceElementIndex = M.value(direction).pipe(M.when('Next', () => Number.increment), M.when('Previous', () => Number.decrement), M.exhaustive)(referenceElementIndex.value);
     const nextElement = Array.get(focusableElements, offsetReferenceElementIndex);
     if (Option.isSome(nextElement)) {
         nextElement.value.focus();
     }
-    return Effect.void;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldkit",
-  "version": "0.82.8",
+  "version": "0.82.9",
   "description": "A TypeScript frontend framework, built on Effect and architected like Elm",
   "type": "module",
   "main": "./dist/index.js",