@gridui/follow-scroll 1.0.1 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,4 +5,4 @@ Core family. Public API: `FollowScroll`, `FollowScrollOptions`, `FollowScrollPro
5
5
  Import components from `@gridui/follow-scroll` and load `@gridui/follow-scroll/styles.css` after Theme.
6
6
  Load styles for any composed dependency used by this family. Applications own routes, labels, state persistence, and branding.
7
7
 
8
- See [component ownership](../../docs/component-ownership.md) and [release history](.changeset/history/).
8
+ See [component ownership](https://github.com/sudo-ui/GridUI-React-Monorepo/blob/main/docs/component-ownership.md) and [release history](https://github.com/sudo-ui/GridUI-React-Monorepo/tree/main/packages-core/follow-scroll/.changeset/history).
package/dist/index.js CHANGED
@@ -36,7 +36,9 @@ var useFollowScroll = ({ threshold = 48, onFollowingChange } = {}) => {
36
36
  const followGrowth = () => {
37
37
  cancelAnimationFrame(frame);
38
38
  frame = requestAnimationFrame(() => {
39
- if (followingRef.current) {
39
+ const distance = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;
40
+ if (followingRef.current || distance <= threshold) {
41
+ changeFollowing(true);
40
42
  viewport.scrollTop = viewport.scrollHeight;
41
43
  }
42
44
  });
package/dist/index.js.map CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "version": 3,
3
3
  "sources": ["../src/follow-scroll/use-follow-scroll.ts", "../src/follow-scroll/follow-scroll.tsx"],
4
- "sourcesContent": ["/**\n * @author WMXPY\n * @package Follow Scroll\n * @namespace FollowScroll\n * @description Use Follow Scroll\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nexport type FollowScrollOptions = {\n readonly threshold?: number;\n readonly onFollowingChange?: (following: boolean) => void;\n};\n\nexport const useFollowScroll = ({ threshold = 48, onFollowingChange }: FollowScrollOptions = {}) => {\n if (!Number.isFinite(threshold) || threshold < 0) {\n throw new Error(\"FollowScroll threshold must be finite and nonnegative.\");\n }\n const viewportRef = useRef<HTMLDivElement>(null);\n const contentRef = useRef<HTMLDivElement>(null);\n const followingRef = useRef(true);\n const [\n following,\n setFollowing,\n ] = useState(true);\n const changeFollowing = useCallback((next: boolean) => {\n if (followingRef.current === next) {\n return;\n }\n followingRef.current = next;\n setFollowing(next);\n onFollowingChange?.(next);\n }, [onFollowingChange]);\n const scrollToEnd = useCallback(() => {\n const viewport = viewportRef.current;\n if (viewport) {\n changeFollowing(true);\n viewport.scrollTop = viewport.scrollHeight;\n }\n }, [changeFollowing]);\n useEffect(() => {\n const viewport = viewportRef.current;\n const content = contentRef.current;\n if (!viewport || !content) {\n return;\n }\n let frame = 0;\n const followGrowth = () => {\n cancelAnimationFrame(frame);\n frame = requestAnimationFrame(() => {\n if (followingRef.current) {\n viewport.scrollTop = viewport.scrollHeight;\n }\n });\n };\n const onScroll = () => {\n const distance = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;\n changeFollowing(distance <= threshold);\n };\n const observer = typeof ResizeObserver === \"undefined\" ? undefined : new ResizeObserver(followGrowth);\n observer?.observe(content);\n observer?.observe(viewport);\n viewport.addEventListener(\"scroll\", onScroll);\n followGrowth();\n return () => {\n cancelAnimationFrame(frame);\n observer?.disconnect();\n viewport.removeEventListener(\"scroll\", onScroll);\n };\n }, [\n threshold,\n changeFollowing,\n ]);\n return {\n viewportRef,\n contentRef,\n following,\n scrollToEnd,\n };\n};\n", "/**\n * @author WMXPY\n * @package Follow Scroll\n * @namespace FollowScroll\n * @description Follow Scroll\n */\n\nimport { type FollowScrollOptions, useFollowScroll } from \"./use-follow-scroll\";\nimport { Button } from \"@gridui/button\";\nimport { cn } from \"@gridui/style-utils\";\nimport type { ComponentPropsWithRef, FC } from \"react\";\n\nexport type FollowScrollProps = Omit<ComponentPropsWithRef<\"div\">, \"onScroll\"> & FollowScrollOptions & {\n readonly label: string;\n readonly jumpLabel: string;\n};\n\nexport const FollowScroll: FC<FollowScrollProps> = (props: FollowScrollProps) => {\n const { label, jumpLabel, threshold, onFollowingChange, children, className, ...restProps } = props;\n const { viewportRef, contentRef, following, scrollToEnd } = useFollowScroll({\n ...(threshold === undefined ? {} : { threshold }),\n ...(onFollowingChange === undefined ? {} : { onFollowingChange }),\n });\n return (<div\n {...restProps}\n className={cn(\"gridui-follow-scroll\", className)}\n >\n <div\n ref={viewportRef}\n className=\"gridui-follow-scroll-viewport\"\n role=\"region\"\n aria-label={label}\n tabIndex={0}\n >\n <div\n ref={contentRef}\n className=\"gridui-follow-scroll-content\"\n >\n {children}\n </div>\n </div>\n {!following && (<Button\n className=\"gridui-follow-scroll-jump\"\n size=\"small\"\n onClick={() => {\n scrollToEnd();\n viewportRef.current?.focus({ preventScroll: true });\n }}\n >\n {jumpLabel}\n </Button>)}\n </div>);\n};\n"],
5
- "mappings": "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",
4
+ "sourcesContent": ["/**\n * @author WMXPY\n * @package Follow Scroll\n * @namespace FollowScroll\n * @description Use Follow Scroll\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nexport type FollowScrollOptions = {\n readonly threshold?: number;\n readonly onFollowingChange?: (following: boolean) => void;\n};\n\nexport const useFollowScroll = ({ threshold = 48, onFollowingChange }: FollowScrollOptions = {}) => {\n if (!Number.isFinite(threshold) || threshold < 0) {\n throw new Error(\"FollowScroll threshold must be finite and nonnegative.\");\n }\n const viewportRef = useRef<HTMLDivElement>(null);\n const contentRef = useRef<HTMLDivElement>(null);\n const followingRef = useRef(true);\n const [\n following,\n setFollowing,\n ] = useState(true);\n const changeFollowing = useCallback((next: boolean) => {\n if (followingRef.current === next) {\n return;\n }\n followingRef.current = next;\n setFollowing(next);\n onFollowingChange?.(next);\n }, [onFollowingChange]);\n const scrollToEnd = useCallback(() => {\n const viewport = viewportRef.current;\n if (viewport) {\n changeFollowing(true);\n viewport.scrollTop = viewport.scrollHeight;\n }\n }, [changeFollowing]);\n useEffect(() => {\n const viewport = viewportRef.current;\n const content = contentRef.current;\n if (!viewport || !content) {\n return;\n }\n let frame = 0;\n const followGrowth = () => {\n cancelAnimationFrame(frame);\n frame = requestAnimationFrame(() => {\n const distance = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;\n if (followingRef.current || distance <= threshold) {\n changeFollowing(true);\n viewport.scrollTop = viewport.scrollHeight;\n }\n });\n };\n const onScroll = () => {\n const distance = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;\n changeFollowing(distance <= threshold);\n };\n const observer = typeof ResizeObserver === \"undefined\" ? undefined : new ResizeObserver(followGrowth);\n observer?.observe(content);\n observer?.observe(viewport);\n viewport.addEventListener(\"scroll\", onScroll);\n followGrowth();\n return () => {\n cancelAnimationFrame(frame);\n observer?.disconnect();\n viewport.removeEventListener(\"scroll\", onScroll);\n };\n }, [\n threshold,\n changeFollowing,\n ]);\n return {\n viewportRef,\n contentRef,\n following,\n scrollToEnd,\n };\n};\n", "/**\n * @author WMXPY\n * @package Follow Scroll\n * @namespace FollowScroll\n * @description Follow Scroll\n */\n\nimport { type FollowScrollOptions, useFollowScroll } from \"./use-follow-scroll\";\nimport { Button } from \"@gridui/button\";\nimport { cn } from \"@gridui/style-utils\";\nimport type { ComponentPropsWithRef, FC } from \"react\";\n\nexport type FollowScrollProps = Omit<ComponentPropsWithRef<\"div\">, \"onScroll\"> & FollowScrollOptions & {\n readonly label: string;\n readonly jumpLabel: string;\n};\n\nexport const FollowScroll: FC<FollowScrollProps> = (props: FollowScrollProps) => {\n const { label, jumpLabel, threshold, onFollowingChange, children, className, ...restProps } = props;\n const { viewportRef, contentRef, following, scrollToEnd } = useFollowScroll({\n ...(threshold === undefined ? {} : { threshold }),\n ...(onFollowingChange === undefined ? {} : { onFollowingChange }),\n });\n return (<div\n {...restProps}\n className={cn(\"gridui-follow-scroll\", className)}\n >\n <div\n ref={viewportRef}\n className=\"gridui-follow-scroll-viewport\"\n role=\"region\"\n aria-label={label}\n tabIndex={0}\n >\n <div\n ref={contentRef}\n className=\"gridui-follow-scroll-content\"\n >\n {children}\n </div>\n </div>\n {!following && (<Button\n className=\"gridui-follow-scroll-jump\"\n size=\"small\"\n onClick={() => {\n scrollToEnd();\n viewportRef.current?.focus({ preventScroll: true });\n }}\n >\n {jumpLabel}\n </Button>)}\n </div>);\n};\n"],
5
+ "mappings": "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",
6
6
  "names": []
7
7
  }
@@ -0,0 +1,33 @@
1
+ # FollowScroll
2
+
3
+ Import `FollowScroll`, `FollowScrollProps`, `useFollowScroll`, and
4
+ `FollowScrollOptions` from `@gridui/follow-scroll`. Load Theme and `@gridui/follow-scroll/styles.css`.
5
+
6
+ ```tsx
7
+ <FollowScroll label="Build output" jumpLabel="Jump to latest" style={{ height: 320 }}>
8
+ {lines.map(line => <p key={line.id}>{line.text}</p>)}
9
+ </FollowScroll>
10
+ ```
11
+
12
+ Give the container a bounded height. Its focusable, labeled region scrolls
13
+ independently. It starts at the end and follows content or viewport size changes
14
+ while the reader is within `threshold` CSS pixels of the end (default 48).
15
+ Scrolling away pauses following. Scrolling back near the end or activating the
16
+ jump button resumes it. Content shrinking or the viewport expanding back to the end
17
+ also resumes following, even when the scroll position does not change. Jumping
18
+ returns focus to the region after the button is removed. Scroll changes are immediate and do not force smooth motion.
19
+
20
+ `onFollowingChange` reports transitions only, not every scroll event. Content
21
+ size observation includes streamed text, expanded details and late-loading
22
+ images; it requires browser `ResizeObserver`. Without it, explicit scrolling and
23
+ manual jump remain usable, but automatic growth observation is unavailable.
24
+ Observers, listeners and queued animation frames are cleaned up on unmount.
25
+
26
+ For custom presentation, `useFollowScroll(options)` returns `viewportRef`,
27
+ `contentRef`, `following`, and `scrollToEnd`. Attach the refs to a persistent
28
+ scrolling div and its content div. Supply your own styles, label, focus policy and
29
+ jump button. Remount with a React `key` when switching to an independent stream.
30
+
31
+ The library does not understand messages or logs, announce streamed content,
32
+ fetch history, virtualize rows, or preserve an anchor while prepending history.
33
+ Applications decide those behaviors and which updates belong to a stream.
package/package.json CHANGED
@@ -1,11 +1,12 @@
1
1
  {
2
2
  "name": "@gridui/follow-scroll",
3
- "version": "1.0.1",
3
+ "version": "1.0.2",
4
4
  "description": "GridUI React follow scroll",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
7
7
  "files": [
8
8
  "dist",
9
+ "docs",
9
10
  "README.md"
10
11
  ],
11
12
  "sideEffects": [
@@ -26,13 +27,14 @@
26
27
  "react-dom": "^19.2.0"
27
28
  },
28
29
  "dependencies": {
29
- "@gridui/button": "^2.1.2",
30
- "@gridui/style-utils": "^2.1.3",
31
- "@gridui/theme": "^2.2.1"
30
+ "@gridui/button": "^2.2.0",
31
+ "@gridui/style-utils": "^2.1.4",
32
+ "@gridui/theme": "^2.3.2"
32
33
  },
33
34
  "devDependencies": {
34
35
  "@gridui-internal/configuration": "0.0.0-internal",
35
36
  "@jest/globals": "30.5.2",
37
+ "@storybook/react-vite": "10.6.5",
36
38
  "@types/jest": "30.0.0",
37
39
  "@types/node": "26.6.6",
38
40
  "@types/react": "19.3.0",