@livx.cc/bare-v3 0.1.0-alpha.24 → 0.1.0-alpha.25

package/dist/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.25",
   "cssSha256": "bcc34a659395a996278e980419d5817fb4ea1a4b5c5f85d66be17ed37fcb5e91",
   "classes": [
     "b3-accordion",
@@ -453,6 +453,7 @@
     "editable-filtered-rows.md",
     "icons.md",
     "motion.md",
+    "scroll-entry.md",
     "start.md"
   ]
 }

package/dist/references/motion.md

@@ -37,6 +37,8 @@ Native `dialog` plus the mounted shared helper provides modal focus/inertness, b
 
 The playground's motion studio shows shared geometry, real DOM reordering, direct pointer tracking and spring return, staged scene entrance, cancellable exit/entry exchange, and a collection sheet. The adjacent collapsed feedback recipes cover pending/error/retry, undo/focus recovery and loading with reserved space. Their illustrative content and simulated operations are not runtime services.
 
+For scroll entrances, default to once per page visit. Observe a stationary section wrapper, animate its children, remember entered sections and unobserve them after entry. Do not reset them when scrolling away, returning to the tab or restoring the page. Repeat only a specifically chosen interaction or an explicit Replay action. Prepare the starting visual state before the first paint; waiting for fonts or starting a hidden frame only after intersection causes visible content to disappear and reappear. Keep content visible if setup cannot run. Reduced motion and keyboard focus must expose waiting content immediately. For the complete once-only lifecycle recipe, read scroll-entry.md on demand. The landing-studio composition demonstrates the policy.
+
 For an expanding card beside text: exit the neighboring copy before moving into its space; reveal the copy only after the return layout completes. Guard each completion against newer input. FLIP preserves geometry but does not prevent sibling intersections.
 
 For view replacement: start an exit; guard its completion with a monotonically increasing request id; if it still owns the transition, update content and enter. Rapid navigation must not commit an obsolete view. Do not await a confirmation animation before enabling the next action.

package/dist/references/scroll-entry.md

@@ -0,0 +1,75 @@
+# Once-only scroll entrances
+
+For a client-rendered page, call this in the framework's post-render hook before paint. For static HTML, use a synchronous script immediately after the section markup. Calling it after fonts, a network request or a paint can cause the original flash. This snippet is not a solution for asynchronously hydrated visible HTML.
+
+Choose one delivery location. On a static page, define and call the routine once in the synchronous script after the markup; do not also generate a fallback TypeScript copy. In a client-rendered app, put it in one module and call it from the pre-paint post-render hook instead. Keep the returned cleanup with that owner. The two delivery choices are alternatives, not parallel implementations.
+
+Mark stationary section wrappers with `data-entry-section` and their animated children with `data-entry-part`. Keep the final layout visible in CSS. The routine prepares paused animations synchronously; setup failure, reduced motion and focus expose final content. Scroll entry is once per mount, with no tab-return reset. Explicit replay belongs to a separate user action.
+
+```js
+function prepareEntrances(root) {
+  const preference = matchMedia('(prefers-reduced-motion: reduce)');
+  const groups = new Map();
+  let observer;
+  let disposed = false;
+  const expose = (section) => {
+    const group = groups.get(section);
+    if (!group) return;
+    group.entered = true;
+    group.animations.forEach(animation => animation.cancel());
+    observer?.unobserve(section);
+  };
+  const exposeAll = () => groups.forEach((_, section) => expose(section));
+  const onPreference = () => { if (preference.matches) exposeAll(); };
+  const onFocus = event => {
+    for (const section of groups.keys()) {
+      if (section.contains(event.target)) expose(section);
+    }
+  };
+  try {
+    for (const section of root.querySelectorAll('[data-entry-section]')) {
+      const group = { entered: preference.matches, animations: [] };
+      groups.set(section, group);
+      if (preference.matches) continue;
+      for (const [index, part] of [...section.querySelectorAll('[data-entry-part]')].entries()) {
+        const animation = part.animate([
+          { opacity: 0, transform: 'translateY(12px)' },
+          { opacity: 1, transform: 'none' }
+        ], { duration: 440, delay: Math.min(index * 70, 210),
+             easing: 'cubic-bezier(.16,1,.3,1)', fill: 'backwards' });
+        group.animations.push(animation);
+        animation.pause();
+        animation.currentTime = 0;
+      }
+    }
+    observer = new IntersectionObserver(entries => {
+      if (disposed) return;
+      for (const entry of entries) {
+        const group = groups.get(entry.target);
+        if (!entry.isIntersecting || group.entered) continue;
+        group.entered = true;
+        group.animations.forEach(animation => animation.play());
+        observer.unobserve(entry.target);
+      }
+    }, { threshold: 0 });
+    groups.forEach((group, section) => { if (!group.entered) observer.observe(section); });
+    preference.addEventListener('change', onPreference);
+    root.addEventListener('focusin', onFocus);
+    // A framework may restore focus before this setup hook runs.
+    onFocus({ target: (root.ownerDocument || root).activeElement });
+  } catch {
+    // Failure must leave the page usable; no hidden CSS depends on successful JS.
+    exposeAll();
+    observer?.disconnect();
+  }
+  return () => {
+    disposed = true;
+    exposeAll();
+    observer?.disconnect();
+    preference.removeEventListener('change', onPreference);
+    root.removeEventListener('focusin', onFocus);
+  };
+}
+```
+
+Assumes window scrolling and untransformed child resting styles. For a scroll container, pass the actual scroll root to IntersectionObserver. Use an inner wrapper when authored transforms must be preserved. Do not infer animation state from truthiness of data attributes. Verify initial offscreen state, first entry, reentry, focus and reduced-motion changes; visible final content alone does not prove entrances ran.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livx.cc/bare-v3",
-  "version": "0.1.0-alpha.24",
+  "version": "0.1.0-alpha.25",
   "type": "module",
   "files": [
     "dist",