foldkit 0.115.0 → 0.116.0

package/dist/dom/dom.d.ts

@@ -125,6 +125,24 @@ export declare const scrollIntoView: (selector: string, options?: Readonly<{
 export declare const scrollIntoViewAfterPaint: (selector: string, options?: Readonly<{
     block?: ScrollLogicalPosition;
 }>) => Effect.Effect<void, ElementNotFound>;
+/**
+ * Like `scrollIntoViewAfterPaint`, but skips the scroll if the element is
+ * already fully visible within its scroll container.
+ *
+ * Defaults to `{ block: 'center' }`; pass a different `block` when the
+ * target should land at a specific position when it does need to scroll.
+ *
+ * Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.
+ *
+ * @example
+ * ```typescript
+ * Dom.scrollIntoViewIfNotVisible('#active-nav-link')
+ * Dom.scrollIntoViewIfNotVisible('#active-nav-link', { block: 'nearest' })
+ * ```
+ */
+export declare const scrollIntoViewIfNotVisible: (selector: string, options?: Readonly<{
+    block?: ScrollLogicalPosition;
+}>) => Effect.Effect<void, ElementNotFound>;
 /** Direction for focus advancement: forward or backward in tab order. */
 export type FocusDirection = 'Next' | 'Previous';
 /**

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

@@ -1 +1 @@
-{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/dom/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAMP,MAAM,QAAQ,CAAA;AAGf,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAiC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,KAAK,GAChB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,KACvE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAQlC,CAAA;AAEJ;;;;;;;;;;;;;;;;;GAiBG;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,CAsElC,CAAA;AAuBJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAyBlC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,CAAC,KACpD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,CAAC,KACpD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ,yEAAyE;AACzE,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"}
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/dom/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,MAAM,EAMP,MAAM,QAAQ,CAAA;AAGf,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAiC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,eAAO,MAAM,KAAK,GAChB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC,KACvE,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAQlC,CAAA;AAEJ;;;;;;;;;;;;;;;;;GAiBG;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,CAsElC,CAAA;AAuBJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,GACrB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAyBlC,CAAA;AAEJ;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,UAAU,MAAM,KACf,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,CAAC,KACpD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAEJ;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,wBAAwB,GACnC,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,CAAC,KACpD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAKlC,CAAA;AAcJ;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,0BAA0B,GACrC,UAAU,MAAM,EAChB,UAAU,QAAQ,CAAC;IAAE,KAAK,CAAC,EAAE,qBAAqB,CAAA;CAAE,CAAC,KACpD,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,eAAe,CAkBlC,CAAA;AAEJ,yEAAyE;AACzE,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/dom/dom.js

@@ -232,6 +232,48 @@ export const scrollIntoViewAfterPaint = (selector, options) => Effect.gen(functi
     const element = yield* queryHTMLElement(selector);
     element.scrollIntoView({ block: options?.block ?? 'nearest' });
 });
+const findScrollParent = (element) => {
+    let candidate = element.parentElement;
+    while (candidate !== null) {
+        const { overflowY } = getComputedStyle(candidate);
+        if (overflowY === 'scroll' || overflowY === 'auto') {
+            return Option.some(candidate);
+        }
+        candidate = candidate.parentElement;
+    }
+    return Option.none();
+};
+/**
+ * Like `scrollIntoViewAfterPaint`, but skips the scroll if the element is
+ * already fully visible within its scroll container.
+ *
+ * Defaults to `{ block: 'center' }`; pass a different `block` when the
+ * target should land at a specific position when it does need to scroll.
+ *
+ * Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.
+ *
+ * @example
+ * ```typescript
+ * Dom.scrollIntoViewIfNotVisible('#active-nav-link')
+ * Dom.scrollIntoViewIfNotVisible('#active-nav-link', { block: 'nearest' })
+ * ```
+ */
+export const scrollIntoViewIfNotVisible = (selector, options) => Effect.gen(function* () {
+    yield* afterPaint;
+    const element = yield* queryHTMLElement(selector);
+    Option.match(findScrollParent(element), {
+        onNone: () => element.scrollIntoView({ block: options?.block ?? 'center' }),
+        onSome: scrollParent => {
+            const parentRect = scrollParent.getBoundingClientRect();
+            const elementRect = element.getBoundingClientRect();
+            const isFullyVisible = elementRect.top >= parentRect.top &&
+                elementRect.bottom <= parentRect.bottom;
+            if (!isFullyVisible) {
+                element.scrollIntoView({ block: options?.block ?? 'center' });
+            }
+        },
+    });
+});
 /**
  * Focuses the next or previous focusable element in the document relative to the element matching the given selector.
  * Fails with `ElementNotFound` if the selector does not match an `HTMLElement`.

package/dist/dom/index.d.ts

@@ -1,5 +1,5 @@
 export { ElementNotFound } from './error.js';
-export { advanceFocus, clickElement, closeModal, focus, scrollIntoView, scrollIntoViewAfterPaint, showModal, } from './dom.js';
+export { advanceFocus, clickElement, closeModal, focus, scrollIntoView, scrollIntoViewAfterPaint, scrollIntoViewIfNotVisible, showModal, } from './dom.js';
 export type { FocusDirection } from './dom.js';
 export { detectElementMovement } from './elementMovement.js';
 export { inertOthers, restoreInert } from './inert.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EACL,cAAc,EACd,wBAAwB,EACxB,SAAS,GACV,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/dom/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAC5C,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,KAAK,EACL,cAAc,EACd,wBAAwB,EACxB,0BAA0B,EAC1B,SAAS,GACV,MAAM,UAAU,CAAA;AACjB,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AAC9C,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACtD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAC1D,OAAO,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/dom/index.js

@@ -1,5 +1,5 @@
 export { ElementNotFound } from './error.js';
-export { advanceFocus, clickElement, closeModal, focus, scrollIntoView, scrollIntoViewAfterPaint, showModal, } from './dom.js';
+export { advanceFocus, clickElement, closeModal, focus, scrollIntoView, scrollIntoViewAfterPaint, scrollIntoViewIfNotVisible, showModal, } from './dom.js';
 export { detectElementMovement } from './elementMovement.js';
 export { inertOthers, restoreInert } from './inert.js';
 export { lockScroll, unlockScroll } from './scrollLock.js';

package/dist/dom/public.d.ts

@@ -1,3 +1,3 @@
-export { ElementNotFound, advanceFocus, clickElement, closeModal, detectElementMovement, focus, inertOthers, lockScroll, restoreInert, scrollIntoView, scrollIntoViewAfterPaint, showModal, unlockScroll, waitForAnimationSettled, } from './index.js';
+export { ElementNotFound, advanceFocus, clickElement, closeModal, detectElementMovement, focus, inertOthers, lockScroll, restoreInert, scrollIntoView, scrollIntoViewAfterPaint, scrollIntoViewIfNotVisible, showModal, unlockScroll, waitForAnimationSettled, } from './index.js';
 export type { FocusDirection } from './index.js';
 //# sourceMappingURL=public.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/dom/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,KAAK,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,SAAS,EACT,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"public.d.ts","sourceRoot":"","sources":["../../src/dom/public.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,YAAY,EACZ,YAAY,EACZ,UAAU,EACV,qBAAqB,EACrB,KAAK,EACL,WAAW,EACX,UAAU,EACV,YAAY,EACZ,cAAc,EACd,wBAAwB,EACxB,0BAA0B,EAC1B,SAAS,EACT,YAAY,EACZ,uBAAuB,GACxB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA"}

package/dist/dom/public.js

@@ -1 +1 @@
-export { ElementNotFound, advanceFocus, clickElement, closeModal, detectElementMovement, focus, inertOthers, lockScroll, restoreInert, scrollIntoView, scrollIntoViewAfterPaint, showModal, unlockScroll, waitForAnimationSettled, } from './index.js';
+export { ElementNotFound, advanceFocus, clickElement, closeModal, detectElementMovement, focus, inertOthers, lockScroll, restoreInert, scrollIntoView, scrollIntoViewAfterPaint, scrollIntoViewIfNotVisible, showModal, unlockScroll, waitForAnimationSettled, } from './index.js';

package/package.json

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