react-snapshot-bridge 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ethan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# react-snapshot-bridge
+
+> Use React's class-only `getSnapshotBeforeUpdate` lifecycle from **function components**, via a single 30-line wrapper.
+
+[![npm](https://img.shields.io/npm/v/react-snapshot-bridge.svg)](https://www.npmjs.com/package/react-snapshot-bridge)
+[![bundle](https://img.shields.io/bundlephobia/minzip/react-snapshot-bridge)](https://bundlephobia.com/package/react-snapshot-bridge)
+[![license](https://img.shields.io/npm/l/react-snapshot-bridge.svg)](./LICENSE)
+
+## Why
+
+`useLayoutEffect` runs **after** the DOM is mutated, so by the time it fires the previous DOM state — old `scrollTop`, prior selection, prior dimensions — is already gone.
+
+`getSnapshotBeforeUpdate` is the React lifecycle that runs **right before** the mutation, returns a "snapshot" value, and forwards it to `componentDidUpdate`. It exists only on class components, and there is no built-in hook equivalent.
+
+This library bridges that gap with a single drop-in wrapper. Use it when you need to:
+
+- Keep the visible content anchored when items are inserted **above** a scroll container (chat lists, feeds)
+- Preserve text selection or caret position across re-renders
+- Capture element dimensions for FLIP-style animations
+- Read any "before commit" DOM state and apply it after the commit
+
+## Install
+
+```bash
+pnpm add react-snapshot-bridge
+# or
+npm i react-snapshot-bridge
+# or
+yarn add react-snapshot-bridge
+```
+
+Peer dependency: `react >= 16.3` (when `getSnapshotBeforeUpdate` was introduced).
+
+## Quick start — preserve scroll on prepend
+
+```tsx
+import { useRef, useState } from 'react';
+import { SnapshotBeforeUpdate } from 'react-snapshot-bridge';
+
+function ChatList() {
+  const scrollerRef = useRef<HTMLDivElement>(null);
+  const [messages, setMessages] = useState<string[]>(['hi']);
+
+  return (
+    <>
+      <button onClick={() => setMessages((m) => ['new message', ...m])}>
+        Prepend
+      </button>
+
+      <SnapshotBeforeUpdate<number>
+        capture={() => {
+          const el = scrollerRef.current!;
+          return el.scrollHeight - el.scrollTop;
+        }}
+        apply={(prevDistanceFromBottom) => {
+          const el = scrollerRef.current!;
+          el.scrollTop = el.scrollHeight - prevDistanceFromBottom;
+        }}
+      >
+        <div ref={scrollerRef} style={{ height: 200, overflow: 'auto' }}>
+          {messages.map((msg, i) => (
+            <div key={i}>{msg}</div>
+          ))}
+        </div>
+      </SnapshotBeforeUpdate>
+    </>
+  );
+}
+```
+
+Without the wrapper, every prepend visually shifts the user's content down. With it, the visible content stays anchored.
+
+## Capturing multiple values
+
+`capture` returns a single value, but that value can be **any shape** — including an object. This is the recommended way to forward multiple pieces of state in one commit, and it keeps the API surface minimal and type-safe.
+
+The example below combines two ideas at once:
+
+1. Capture two DOM-derived values (`distanceFromBottom`, `wasAtBottom`) into one snapshot.
+2. Reach into the surrounding component's state via **closure** (`messages.length`) so `apply` can compare "before" with "after" without a separate ref.
+
+```tsx
+import { useRef, useState } from 'react';
+import { SnapshotBeforeUpdate } from 'react-snapshot-bridge';
+
+type Snap = {
+  distanceFromBottom: number;
+  wasAtBottom: boolean;
+  prevCount: number;
+};
+
+function ChatList({ messages }: { messages: string[] }) {
+  const scrollerRef = useRef<HTMLDivElement>(null);
+
+  return (
+    <SnapshotBeforeUpdate<Snap>
+      capture={() => {
+        const el = scrollerRef.current!;
+        const distanceFromBottom = el.scrollHeight - el.scrollTop - el.clientHeight;
+        return {
+          distanceFromBottom,
+          wasAtBottom: distanceFromBottom < 16,
+          // `messages` here is the value at this commit — by the time `apply`
+          // runs, the closure inside `apply` will see the new `messages`.
+          prevCount: messages.length,
+        };
+      }}
+      apply={({ distanceFromBottom, wasAtBottom, prevCount }) => {
+        const el = scrollerRef.current!;
+        const grewAtTop = messages.length > prevCount;
+
+        if (wasAtBottom) {
+          el.scrollTop = el.scrollHeight; // stick to bottom for new arrivals
+        } else if (grewAtTop) {
+          el.scrollTop = el.scrollHeight - distanceFromBottom; // anchor existing content
+        }
+      }}
+    >
+      <div ref={scrollerRef} style={{ height: 200, overflow: 'auto' }}>
+        {messages.map((msg, i) => (
+          <div key={i}>{msg}</div>
+        ))}
+      </div>
+    </SnapshotBeforeUpdate>
+  );
+}
+```
+
+> Why not pass `prevProps` / `prevState` directly into `apply`? Because the wrapper would only see its own internal props (`{ capture, apply, children }`) and an empty state — neither has anything to do with your component. Capturing what you actually need via closure is both safer and clearer.
+
+## API
+
+### `<SnapshotBeforeUpdate<T> capture apply>{children?}</SnapshotBeforeUpdate>`
+
+| Prop       | Type                          | Required | Description                                                                                  |
+| ---------- | ----------------------------- | -------- | -------------------------------------------------------------------------------------------- |
+| `capture`  | `() => T`                     | yes      | Called synchronously **before** DOM mutation. Return value is forwarded to `apply`.          |
+| `apply`    | `(snapshot: T) => void`       | yes      | Called synchronously **after** DOM mutation, before paint. Receives the value from `capture`. |
+| `children` | `React.ReactNode`             | no       | Optional. When provided, rendered as-is (wrapper pattern). When omitted, renders nothing.    |
+
+The generic `T` is inferred from `capture`'s return type — you usually don't need to specify it.
+
+## How it works
+
+React's commit phase runs in this order:
+
+```
+Render → Before Mutation → DOM Mutation → After Mutation → Paint → Passive
+                ▲                                ▲
+                │                                │
+       getSnapshotBeforeUpdate           cDU + useLayoutEffect
+```
+
+Function components only have hooks for the **After Mutation** slot (`useLayoutEffect`). This library renders a tiny class component into your tree whose sole job is to occupy the **Before Mutation** slot and call your `capture` callback there.
+
+The captured value is forwarded to `componentDidUpdate`, which calls `apply`. From your function component's point of view, you get a clean `(capture, apply)` pair without ever touching a class.
+
+## Caveats
+
+- **No call on initial mount.** Like the underlying class lifecycle, neither `capture` nor `apply` runs the first time the component appears — only on subsequent updates.
+- **Requires a re-render.** If a `React.memo` (or `shouldComponentUpdate`) ancestor short-circuits the render, the bridge will not fire either. Make sure the component is in a tree that actually re-renders when the relevant change happens.
+- **Concurrent rendering safe.** React 18+ concurrent features may discard render results, but the commit phase itself is synchronous, so `capture`/`apply` always run as a paired set.
+- **SSR safe.** Lifecycle methods don't run during `renderToString` / `renderToPipeableStream`, so the bridge is a no-op on the server.
+- **React 19.** Class components and `getSnapshotBeforeUpdate` are not deprecated in React 19. This library remains compatible.
+
+## License
+
+[MIT](./LICENSE)

package/dist/index.cjs

@@ -0,0 +1,20 @@
+'use strict';
+
+var react = require('react');
+
+// src/SnapshotBeforeUpdate.tsx
+var SnapshotBeforeUpdate = class extends react.Component {
+  getSnapshotBeforeUpdate() {
+    return this.props.capture();
+  }
+  componentDidUpdate(_prevProps, _prevState, snapshot) {
+    this.props.apply(snapshot);
+  }
+  render() {
+    return this.props.children ?? null;
+  }
+};
+
+exports.SnapshotBeforeUpdate = SnapshotBeforeUpdate;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/SnapshotBeforeUpdate.tsx"],"names":["Component"],"mappings":";;;;;AAkCO,IAAM,oBAAA,GAAN,cAAgDA,eAAA,CAGrD;AAAA,EACS,uBAAA,GAA6B;AACpC,IAAA,OAAO,IAAA,CAAK,MAAM,OAAA,EAAQ;AAAA,EAC5B;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAA,CAAK,KAAA,CAAM,MAAM,QAAQ,CAAA;AAAA,EAC3B;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.cjs","sourcesContent":["import { Component } from \"react\";\nimport type { ReactNode } from \"react\";\n\ntype EmptyState = Record<string, never>;\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState\n> {\n  override getSnapshotBeforeUpdate(): T {\n    return this.props.capture();\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: T,\n  ): void {\n    this.props.apply(snapshot);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,36 @@
+import { Component, ReactNode } from 'react';
+
+type EmptyState = Record<string, never>;
+interface SnapshotBeforeUpdateProps<T> {
+    /**
+     * Runs synchronously **before** the DOM is mutated for this commit.
+     * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.
+     */
+    capture: () => T;
+    /**
+     * Runs synchronously **after** the DOM is mutated, before the browser paints.
+     * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.
+     */
+    apply: (snapshot: T) => void;
+    /**
+     * Optional children. When provided, this component acts as a wrapper and
+     * renders its children. When omitted, it renders nothing and you can place
+     * it as a sibling next to the elements you care about.
+     */
+    children?: ReactNode;
+}
+/**
+ * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees
+ * built with function components.
+ *
+ * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`
+ * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}
+ * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.
+ */
+declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState> {
+    getSnapshotBeforeUpdate(): T;
+    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: T): void;
+    render(): ReactNode;
+}
+
+export { SnapshotBeforeUpdate, type SnapshotBeforeUpdateProps };

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+import { Component, ReactNode } from 'react';
+
+type EmptyState = Record<string, never>;
+interface SnapshotBeforeUpdateProps<T> {
+    /**
+     * Runs synchronously **before** the DOM is mutated for this commit.
+     * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.
+     */
+    capture: () => T;
+    /**
+     * Runs synchronously **after** the DOM is mutated, before the browser paints.
+     * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.
+     */
+    apply: (snapshot: T) => void;
+    /**
+     * Optional children. When provided, this component acts as a wrapper and
+     * renders its children. When omitted, it renders nothing and you can place
+     * it as a sibling next to the elements you care about.
+     */
+    children?: ReactNode;
+}
+/**
+ * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees
+ * built with function components.
+ *
+ * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`
+ * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}
+ * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.
+ */
+declare class SnapshotBeforeUpdate<T = unknown> extends Component<SnapshotBeforeUpdateProps<T>, EmptyState> {
+    getSnapshotBeforeUpdate(): T;
+    componentDidUpdate(_prevProps: Readonly<SnapshotBeforeUpdateProps<T>>, _prevState: Readonly<EmptyState>, snapshot: T): void;
+    render(): ReactNode;
+}
+
+export { SnapshotBeforeUpdate, type SnapshotBeforeUpdateProps };

package/dist/index.js

@@ -0,0 +1,18 @@
+import { Component } from 'react';
+
+// src/SnapshotBeforeUpdate.tsx
+var SnapshotBeforeUpdate = class extends Component {
+  getSnapshotBeforeUpdate() {
+    return this.props.capture();
+  }
+  componentDidUpdate(_prevProps, _prevState, snapshot) {
+    this.props.apply(snapshot);
+  }
+  render() {
+    return this.props.children ?? null;
+  }
+};
+
+export { SnapshotBeforeUpdate };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/SnapshotBeforeUpdate.tsx"],"names":[],"mappings":";;;AAkCO,IAAM,oBAAA,GAAN,cAAgD,SAAA,CAGrD;AAAA,EACS,uBAAA,GAA6B;AACpC,IAAA,OAAO,IAAA,CAAK,MAAM,OAAA,EAAQ;AAAA,EAC5B;AAAA,EAES,kBAAA,CACP,UAAA,EACA,UAAA,EACA,QAAA,EACM;AACN,IAAA,IAAA,CAAK,KAAA,CAAM,MAAM,QAAQ,CAAA;AAAA,EAC3B;AAAA,EAES,MAAA,GAAoB;AAC3B,IAAA,OAAO,IAAA,CAAK,MAAM,QAAA,IAAY,IAAA;AAAA,EAChC;AACF","file":"index.js","sourcesContent":["import { Component } from \"react\";\nimport type { ReactNode } from \"react\";\n\ntype EmptyState = Record<string, never>;\n\nexport interface SnapshotBeforeUpdateProps<T> {\n  /**\n   * Runs synchronously **before** the DOM is mutated for this commit.\n   * Whatever you return here is forwarded to {@link SnapshotBeforeUpdateProps.apply}.\n   */\n  capture: () => T;\n\n  /**\n   * Runs synchronously **after** the DOM is mutated, before the browser paints.\n   * Receives the value previously returned from {@link SnapshotBeforeUpdateProps.capture}.\n   */\n  apply: (snapshot: T) => void;\n\n  /**\n   * Optional children. When provided, this component acts as a wrapper and\n   * renders its children. When omitted, it renders nothing and you can place\n   * it as a sibling next to the elements you care about.\n   */\n  children?: ReactNode;\n}\n\n/**\n * Bridges React's class-only `getSnapshotBeforeUpdate` lifecycle into trees\n * built with function components.\n *\n * The component re-renders alongside its parent and uses the `getSnapshotBeforeUpdate`\n * / `componentDidUpdate` pair internally to invoke {@link SnapshotBeforeUpdateProps.capture}\n * before DOM mutation and {@link SnapshotBeforeUpdateProps.apply} immediately after.\n */\nexport class SnapshotBeforeUpdate<T = unknown> extends Component<\n  SnapshotBeforeUpdateProps<T>,\n  EmptyState\n> {\n  override getSnapshotBeforeUpdate(): T {\n    return this.props.capture();\n  }\n\n  override componentDidUpdate(\n    _prevProps: Readonly<SnapshotBeforeUpdateProps<T>>,\n    _prevState: Readonly<EmptyState>,\n    snapshot: T,\n  ): void {\n    this.props.apply(snapshot);\n  }\n\n  override render(): ReactNode {\n    return this.props.children ?? null;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "react-snapshot-bridge",
+  "version": "0.1.0",
+  "description": "Alternative GetSnapshotBeforeUpdate Hook for React Functional Components",
+  "keywords": [
+    "react",
+    "getSnapshotBeforeUpdate",
+    "lifecycle",
+    "snapshot",
+    "hooks",
+    "useLayoutEffect",
+    "before-mutation"
+  ],
+  "author": {
+    "name": "ksr20612",
+    "url": "https://github.com/ksr20612"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ksr20612/react-snapshot-bridge.git",
+    "directory": "packages/react-snapshot-bridge"
+  },
+  "homepage": "https://github.com/ksr20612/react-snapshot-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/ksr20612/react-snapshot-bridge/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": ["dist", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "peerDependencies": {
+    "react": ">=16.3.0"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}