rytm-webflow 2.2.7 → 2.3.1

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git fetch:*)",
+      "mcp__metrum__get_task",
+      "Bash(git checkout:*)",
+      "mcp__metrum__set_subtask_status",
+      "Bash(npm run:*)"
+    ]
+  },
+  "enableAllProjectMcpServers": true,
+  "enabledMcpjsonServers": [
+    "metrum"
+  ]
+}

package/.claude/task_notes/WWT3.md

@@ -0,0 +1,44 @@
+# WWT3 — Remove Bootstrap dependency for default use
+
+## Summary
+Bootstrap 5 helpers were hardcoded into the main `rytm-webflow` bundle, causing bundler errors in non-Bootstrap projects (e.g. Tailwind CSS). The helpers have been moved to an opt-in sub-path export (`'rytm-webflow/bootstrap'`) and the long-standing export name typo (`bootsrap5` → `bootstrap5`) has been corrected. The main import is now fully Bootstrap-free.
+
+## Completed
+- Remove `bootsrap5` import and export from `scripts/index.js`
+- Create `scripts/bootstrap/index.js` as a secondary entry point exporting `bootstrap5`
+- Create `scripts/bootstrap/index.d.ts` with types for the sub-path export
+- Remove `bootsrap5` from the default export shape in `scripts/index.d.ts`
+- Add `exports` field to `package.json` mapping `'.'` and `'./bootstrap'` sub-paths (with `import` + `types` conditions)
+- Rename `bootsrap5` → `bootstrap5` across all source files, types, `CLAUDE.md`, and `README.md`
+- Remove the "Note: the export name has a typo" line from `CLAUDE.md`
+- Update `README.md` Bootstrap integration example to use sub-path import
+- Bump version `2.2.7` → `2.3.0` in `package.json`
+- Create `docs/changelog/2.3.0.md` documenting both breaking changes with upgrade table
+
+## Remaining work
+None — task complete.
+
+## Key decisions
+- **Option B chosen** (sub-path export) over dynamic import or `window.bootstrap` fallback — cleanest separation, no async complexity, standard pattern for optional peer dependencies
+- **Both breaking changes in one version bump** — the rename and the sub-path move are coupled; doing them together avoids an intermediate version that is still broken for Tailwind projects
+- `bootstrap` is intentionally NOT added to `peerDependencies` in `package.json` — it remains the host project's responsibility, consistent with prior behaviour
+- The old typo name `bootsrap5` is preserved in the changelog for upgrade searchability, but removed from all live code
+
+## Gotchas & notes
+- `scripts/bootstrap/v5/Bootstrap5.js` already used the correctly-spelled internal variable `bootstrap5` — only the re-export names needed fixing
+- The `exports` field in `package.json` takes precedence over `main`/`types` in modern bundlers; both are kept for backwards compatibility with older tooling
+- Any legacy project using `RytmWebflow.bootsrap5` will get a runtime error after upgrading — direct them to `docs/changelog/2.3.0.md`
+
+## Key files
+
+| File | Description |
+|---|---|
+| `scripts/index.js` | Main entry — Bootstrap import removed |
+| `scripts/bootstrap/index.js` | New opt-in sub-path entry point |
+| `scripts/bootstrap/index.d.ts` | Types for sub-path export |
+| `scripts/index.d.ts` | `bootsrap5` removed from default export shape |
+| `scripts/bootstrap/v5/Bootstrap5.js` | Unchanged — internal variable was already correct |
+| `package.json` | Version bump to 2.3.0; `exports` field added |
+| `docs/changelog/2.3.0.md` | Upgrade guide for legacy projects |
+| `CLAUDE.md` | Bootstrap section updated to sub-path usage |
+| `README.md` | Bootstrap integration example updated |

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "metrum": {
+      "command": "node",
+      "args": ["/Users/rk/Sites/metrum.rytm.org/mcp/server.js"]
+    }
+  }
+}

package/CLAUDE.md

@@ -19,7 +19,7 @@ import RytmWebflow from 'rytm-webflow'
 | `View` | Class | Base view — animation hooks |
 | `WebflowView` | Class | View with declarative animations via data attributes |
 | `WebflowListView` | Class | Staggered list animations with scroll triggers |
-| `bootsrap5` | Object | Bootstrap 5 modal/offcanvas close helpers |
+| `bootstrap5` | Object | Bootstrap 5 modal/offcanvas close helpers (import from `'rytm-webflow/bootstrap'`) |
 | `scrollController` | Singleton | ScrollMagic controller manager |
 | `showUp` | Singleton | Standalone scroll-triggered animations (no ASwap needed) |
 | `getWebflowProps(str)` | Function | Parse webflow show/hide syntax |
@@ -331,12 +331,12 @@ const aswapEvents = {
 ## Bootstrap 5 helpers
 
 ```javascript
-RytmWebflow.bootsrap5.hideFlyovers()    // Close all modals + offcanvases
-RytmWebflow.bootsrap5.hideModals()      // Close modals only
-RytmWebflow.bootsrap5.hideOffcanvases() // Close offcanvases only
-```
+import bootstrap5 from 'rytm-webflow/bootstrap'
 
-Note: the export name has a typo (`bootsrap5`, not `bootstrap5`).
+bootstrap5.hideFlyovers()    // Close all modals + offcanvases
+bootstrap5.hideModals()      // Close modals only
+bootstrap5.hideOffcanvases() // Close offcanvases only
+```
 
 ---
 
@@ -356,7 +356,7 @@ RytmWebflow.scrollController.destroy()   // Clean up
 2. **Layout shifts from images** — use `ControllerImgLoad` for image-heavy pages
 3. **Nested view element leaks** — filter with `elementBelongsToView()` when querying elements
 4. **ScrollMagic memory leaks** — WebflowView handles cleanup automatically; manual scenes need explicit `destroy()`
-5. **Bootstrap modals persist on navigation** — call `bootsrap5.hideFlyovers()` in `onViewHide`
+5. **Bootstrap modals persist on navigation** — call `bootstrap5.hideFlyovers()` in `onViewHide`
 6. **Event listener accumulation** — always clean up in `removeEventListeners()`
 7. **Stagger not working** — requires `data-webset="selector:..."` attribute
 8. **Easing not applied** — use GSAP v3 syntax: `e:power3.out` (not `e:Power3.easeOut`)

package/README.md

@@ -210,14 +210,15 @@ RytmWebflow.aswap.init(params, {
 
 ### Bootstrap integration ###
 #### Bootstrap v5 ####
-A common situation is to hide all Bootstrap offcanvases or modals when an ASwap page transition is in made. To do so just call the `RytmWebflow.bootsrap5.hideFlyovers()` method. You can also hide offcanvases or modals separatly by calling the `RytmWebflow.bootsrap5.hideOffcanvases()` or `RytmWebflow.bootsrap5.hideModals()` methods.  
+A common situation is to hide all Bootstrap offcanvases or modals when an ASwap page transition is in made. To do so just call the `bootstrap5.hideFlyovers()` method. You can also hide offcanvases or modals separatly by calling the `bootstrap5.hideOffcanvases()` or `bootstrap5.hideModals()` methods.
 A basic usage example:
 ```js
 import RytmWebflow from 'rytm-webflow'
+import bootstrap5 from 'rytm-webflow/bootstrap'
 
 RytmWebflow.aswap.init(params, {
   onViewHide: () => {
-    RytmWebflow.bootsrap5.hideFlyovers()
+    bootstrap5.hideFlyovers()
   },
 })
 ```

package/docs/changelog/2.3.0.md

@@ -0,0 +1,70 @@
+# 2.3.0 — Bootstrap 5 helpers made optional
+
+**Released:** 2026-03-31
+
+## Summary
+
+The Bootstrap 5 helper has been moved out of the main bundle into a dedicated sub-path export, and its long-standing export name typo has been corrected. Projects that do not use Bootstrap (e.g. Tailwind CSS projects) no longer have a transitive dependency on the `bootstrap` package.
+
+## Breaking changes
+
+### 1. Renamed: `bootsrap5` → `bootstrap5`
+
+The export name had a typo (missing `t`). It is now correctly spelled `bootstrap5`.
+
+### 2. Moved to a sub-path import
+
+`bootstrap5` is no longer part of the default `'rytm-webflow'` export. It must be imported from `'rytm-webflow/bootstrap'`.
+
+**Before (≤ 2.2.x):**
+```js
+import RytmWebflow from 'rytm-webflow'
+
+RytmWebflow.bootsrap5.hideFlyovers()
+```
+
+**After (≥ 2.3.0):**
+```js
+import bootstrap5 from 'rytm-webflow/bootstrap'
+
+bootstrap5.hideFlyovers()
+```
+
+## Upgrade guide for legacy projects
+
+1. **Search your codebase** for the old typo name:
+   ```
+   bootsrap5
+   ```
+
+2. **Add the sub-path import** at the top of any file that uses the Bootstrap helpers:
+   ```js
+   import bootstrap5 from 'rytm-webflow/bootstrap'
+   ```
+
+3. **Replace** all `RytmWebflow.bootsrap5.xxx()` calls:
+   | Before | After |
+   |---|---|
+   | `RytmWebflow.bootsrap5.hideFlyovers()` | `bootstrap5.hideFlyovers()` |
+   | `RytmWebflow.bootsrap5.hideModals()` | `bootstrap5.hideModals()` |
+   | `RytmWebflow.bootsrap5.hideOffcanvases()` | `bootstrap5.hideOffcanvases()` |
+
+4. **Verify** `bootstrap` is listed in your project's own `dependencies` or is loaded globally — `rytm-webflow` no longer pulls it in transitively.
+
+## Available helpers (unchanged)
+
+```js
+import bootstrap5 from 'rytm-webflow/bootstrap'
+
+bootstrap5.hideFlyovers()    // Close all modals + offcanvases
+bootstrap5.hideModals()      // Close modals only
+bootstrap5.hideOffcanvases() // Close offcanvases only
+```
+
+## Non-Bootstrap projects
+
+No action required. The main import is unchanged and carries no Bootstrap dependency:
+
+```js
+import RytmWebflow from 'rytm-webflow'
+```

package/package.json

@@ -1,9 +1,19 @@
 {
   "name": "rytm-webflow",
-  "version": "2.2.7",
+  "version": "2.3.1",
   "description": "rytm webflow pack - ASwap, ShowUp",
   "main": "scripts/index.js",
   "types": "scripts/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./scripts/index.js",
+      "types": "./scripts/index.d.ts"
+    },
+    "./bootstrap": {
+      "import": "./scripts/bootstrap/index.js",
+      "types": "./scripts/bootstrap/index.d.ts"
+    }
+  },
   "scripts": {
     "update": "git pull",
     "push": "git add . && git commit -a -m \"$m\" && git push"

package/scripts/aswap/WebflowListView.js

@@ -1,6 +1,10 @@
+import ScrollMagic from 'scrollmagic';
 import gsap from 'gsap';
 import View from './View';
+import scrollController from './../showup/ScrollController';
 import { getWebflowAnimationProps, parseProps } from './../lib/dataTweenParser';
+import { getScrollMagicSceneProps } from './../lib/dataScrollMagicParser';
+import { elementIsVisibleInViewport } from '../lib/helpers';
 import { CLASS_NAME_WEBSCROLL_FIRED } from './WebflowView';
 
 // data-webscroll-... (scroll magic)
@@ -14,6 +18,7 @@ class WebflowListView extends View {
 
   constructor(id) {
     super(id);
+    this.scenes = [];
   }
   /**
   * animate in (show)
@@ -25,8 +30,15 @@ class WebflowListView extends View {
       console.warn("Unknown selector for WebflowListView", this);
       return;
     }
-    const list = [...container.querySelectorAll(this.webset.selector)].filter(this.elementBelongsToView);
-    list.forEach(this.listElementShow.bind(this));
+    const items = [...container.querySelectorAll(this.webset.selector)].filter(this.elementBelongsToView);
+    // 1. Set initial state for ALL scroll elements (regardless of viewport)
+    this.hideAllScrollElements(items);
+    // 2. Stagger-animate in-viewport items (existing behavior)
+    items.forEach(this.listElementShow.bind(this));
+    // 3. Build ScrollMagic scenes for off-screen items
+    this.buildScrollScenesForOffscreenItems(items);
+    // 4. Listen for resize to refresh ScrollMagic
+    this.addEventListeners();
   }
   /**
   * animate out (hide)
@@ -40,6 +52,16 @@ class WebflowListView extends View {
     }
     const list = [...container.querySelectorAll(this.webset.selector)].filter(this.elementBelongsToView);
     list.forEach(this.listElementHide.bind(this));
+    // Also hide off-screen scroll elements that have ScrollMagic scenes
+    this.hideOffscreenScrollElements(container);
+  }
+  /**
+  * hidden (cleanup after hide animation)
+  **/
+  hidden(container) {
+    super.hidden(container);
+    this.removeEventListeners();
+    this.destroyScenes();
   }
   /**
    * ############
@@ -106,6 +128,122 @@ class WebflowListView extends View {
       });
     }
   }
+  /**
+   * ##################
+   * ### DOM events ###
+   * ##################
+   */
+  handleEvent(e) {
+    switch (e.type) {
+      case 'resize':
+      case 'DOMContentLoaded':
+        this.onWindowUpdate();
+        break;
+    }
+  }
+  addEventListeners() {
+    window.addEventListener('resize', this);
+    document.addEventListener('DOMContentLoaded', this);
+  }
+  removeEventListeners() {
+    window.removeEventListener('resize', this);
+    document.removeEventListener('DOMContentLoaded', this);
+  }
+  onWindowUpdate() {
+    if (this.scenes.length > 0) {
+      scrollController.refresh();
+    }
+  }
+  /**
+   * #####################
+   * ### SCROLL SCENES ###
+   * #####################
+   */
+  // set initial state for all scroll elements in list items
+  hideAllScrollElements(items) {
+    items.forEach((el) => {
+      const scrollEls = [...el.querySelectorAll('*[data-' + DATA_ATTR_WEBSCROLL_SHOW + ']')]
+        .filter(this.elementBelongsToView);
+      scrollEls.forEach((scrollEl) => {
+        const propsInitial = this.getTweenProps(scrollEl, DATA_ATTR_WEBSCROLL_INIT);
+        if (propsInitial) {
+          gsap.killTweensOf(scrollEl);
+          gsap.set(scrollEl, { ...propsInitial.tween });
+        }
+      });
+    });
+  }
+  // build ScrollMagic scenes for off-screen list items
+  buildScrollScenesForOffscreenItems(items) {
+    items.forEach((el) => {
+      if (this.isElementInViewport(el)) return;
+      const scrollEls = [...el.querySelectorAll('*[data-' + DATA_ATTR_WEBSCROLL_SHOW + ']')]
+        .filter(this.elementBelongsToView);
+      scrollEls.forEach((scrollEl) => {
+        this.buildScrollmagicScene(scrollEl);
+      });
+    });
+  }
+  // build a single ScrollMagic scene for a scroll element
+  buildScrollmagicScene(el) {
+    const propsInitial = this.getTweenProps(el, DATA_ATTR_WEBSCROLL_INIT);
+    const propsShow = this.getTweenProps(el, DATA_ATTR_WEBSCROLL_SHOW);
+    const setup = parseProps(el.dataset[DATA_ATTR_SETUP] || '');
+    if (propsInitial && propsShow) {
+      const smsp = getScrollMagicSceneProps(el, setup);
+      const scene = new ScrollMagic.Scene(smsp);
+      scene.on("start", (e) => {
+        if (el.classList.contains(CLASS_NAME_WEBSCROLL_FIRED)) return;
+        if (e.scrollDirection === "FORWARD") {
+          gsap.killTweensOf(el);
+          gsap.set(el, { ...propsInitial.tween });
+          gsap.to(el, {
+            duration: propsShow.time,
+            ...propsShow.tween,
+            onComplete: () => {
+              el.classList.add(CLASS_NAME_WEBSCROLL_FIRED);
+            }
+          });
+        }
+      });
+      scene.on("add", () => {
+        setTimeout(() => {
+          if (elementIsVisibleInViewport(el, true)) {
+            gsap.to(el, {
+              duration: propsShow.time,
+              ...propsShow.tween,
+              onComplete: () => {
+                el.classList.add(CLASS_NAME_WEBSCROLL_FIRED);
+              }
+            });
+          }
+        }, 10);
+      });
+      scene.addTo(scrollController.get());
+      this.scenes.push(scene);
+    }
+  }
+  // hide off-screen scroll elements during view hide
+  hideOffscreenScrollElements(container) {
+    const scrollEls = [...container.querySelectorAll('*[data-' + DATA_ATTR_WEBSCROLL_HIDE + ']')]
+      .filter(this.elementBelongsToView);
+    scrollEls.forEach((el) => {
+      if (this.isElementInViewport(el.closest(this.webset.selector))) return;
+      const propsHide = this.getTweenProps(el, DATA_ATTR_WEBSCROLL_HIDE);
+      if (propsHide) {
+        gsap.killTweensOf(el);
+        gsap.to(el, { duration: propsHide.time, ...propsHide.tween });
+      }
+    });
+  }
+  // destroy all ScrollMagic scenes
+  destroyScenes() {
+    this.scenes.forEach((scene) => {
+      scene.destroy();
+      scene = null;
+    });
+    this.scenes = [];
+  }
   /**
    * ###############
    * ### HELPERS ###

package/scripts/bootstrap/index.d.ts

@@ -0,0 +1,8 @@
+export interface Bootstrap5 {
+  hideFlyovers(): void;
+  hideModals(): void;
+  hideOffcanvases(): void;
+}
+
+export declare const bootstrap5: Bootstrap5;
+export default bootstrap5;

package/scripts/bootstrap/index.js

@@ -0,0 +1,4 @@
+import bootstrap5 from './v5/Bootstrap5'
+
+export { bootstrap5 }
+export default bootstrap5

package/scripts/index.d.ts

@@ -201,8 +201,6 @@ declare const RytmWebflow: {
   View: typeof View;
   WebflowView: typeof WebflowView;
   WebflowListView: typeof WebflowListView;
-  /** Note: "bootsrap5" is the original (typo) name in the library */
-  bootsrap5: Bootstrap5;
   scrollController: ScrollController;
   showUp: ShowUp;
   getWebflowProps: typeof getWebflowProps;

package/scripts/index.js

@@ -4,8 +4,6 @@ import ControllerImgLoad from './aswap/ControllerImgLoad'
 import View from './aswap/View'
 import WebflowView from './aswap/WebflowView'
 import WebflowListView from './aswap/WebflowListView'
-// Bootstrap v5 helper
-import bootsrap5 from './bootstrap/v5/Bootstrap5'
 // showup
 import scrollController from './showup/ScrollController'
 import showUp from './showup/ShowUp'
@@ -20,8 +18,6 @@ export default {
   View,
   WebflowView,
   WebflowListView,
-  // boottstrap
-  bootsrap5,
   // showup
   scrollController,
   showUp,