@gridui/follow-scroll 0.0.0-stage → 0.0.0

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
@@ -1,3 +1,8 @@
1
- # Temporary Holding Version
1
+ # @gridui/follow-scroll
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Core family. Public API: `FollowScroll`, `FollowScrollOptions`, `FollowScrollProps`, `useFollowScroll`.
4
+
5
+ Import components from `@gridui/follow-scroll` and load `@gridui/follow-scroll/styles.css` after Theme.
6
+ Load styles for any composed dependency used by this family. Applications own routes, labels, state persistence, and branding.
7
+
8
+ See [component ownership](../../docs/component-ownership.md) and [release history](.changeset/history/).
@@ -0,0 +1,13 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Follow Scroll
4
+ * @namespace FollowScroll
5
+ * @description Follow Scroll
6
+ */
7
+ import { type FollowScrollOptions } from "./use-follow-scroll";
8
+ import type { ComponentPropsWithRef, FC } from "react";
9
+ export type FollowScrollProps = Omit<ComponentPropsWithRef<"div">, "onScroll"> & FollowScrollOptions & {
10
+ readonly label: string;
11
+ readonly jumpLabel: string;
12
+ };
13
+ export declare const FollowScroll: FC<FollowScrollProps>;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Follow Scroll
4
+ * @namespace FollowScroll
5
+ * @description Use Follow Scroll
6
+ */
7
+ export type FollowScrollOptions = {
8
+ readonly threshold?: number;
9
+ readonly onFollowingChange?: (following: boolean) => void;
10
+ };
11
+ export declare const useFollowScroll: ({ threshold, onFollowingChange }?: FollowScrollOptions) => {
12
+ viewportRef: import("react").RefObject<HTMLDivElement | null>;
13
+ contentRef: import("react").RefObject<HTMLDivElement | null>;
14
+ following: boolean;
15
+ scrollToEnd: () => void;
16
+ };
@@ -0,0 +1,10 @@
1
+ /**
2
+ * @author WMXPY
3
+ * @package Follow Scroll
4
+ * @namespace Root
5
+ * @description Index
6
+ */
7
+ export type { FollowScrollProps } from "./follow-scroll/follow-scroll";
8
+ export { FollowScroll } from "./follow-scroll/follow-scroll";
9
+ export type { FollowScrollOptions } from "./follow-scroll/use-follow-scroll";
10
+ export { useFollowScroll } from "./follow-scroll/use-follow-scroll";
package/dist/index.js ADDED
@@ -0,0 +1,124 @@
1
+ // src/follow-scroll/use-follow-scroll.ts
2
+ import { useCallback, useEffect, useRef, useState } from "react";
3
+ var useFollowScroll = ({ threshold = 48, onFollowingChange } = {}) => {
4
+ if (!Number.isFinite(threshold) || threshold < 0) {
5
+ throw new Error("FollowScroll threshold must be finite and nonnegative.");
6
+ }
7
+ const viewportRef = useRef(null);
8
+ const contentRef = useRef(null);
9
+ const followingRef = useRef(true);
10
+ const [
11
+ following,
12
+ setFollowing
13
+ ] = useState(true);
14
+ const changeFollowing = useCallback((next) => {
15
+ if (followingRef.current === next) {
16
+ return;
17
+ }
18
+ followingRef.current = next;
19
+ setFollowing(next);
20
+ onFollowingChange?.(next);
21
+ }, [onFollowingChange]);
22
+ const scrollToEnd = useCallback(() => {
23
+ const viewport = viewportRef.current;
24
+ if (viewport) {
25
+ changeFollowing(true);
26
+ viewport.scrollTop = viewport.scrollHeight;
27
+ }
28
+ }, [changeFollowing]);
29
+ useEffect(() => {
30
+ const viewport = viewportRef.current;
31
+ const content = contentRef.current;
32
+ if (!viewport || !content) {
33
+ return;
34
+ }
35
+ let frame = 0;
36
+ const followGrowth = () => {
37
+ cancelAnimationFrame(frame);
38
+ frame = requestAnimationFrame(() => {
39
+ if (followingRef.current) {
40
+ viewport.scrollTop = viewport.scrollHeight;
41
+ }
42
+ });
43
+ };
44
+ const onScroll = () => {
45
+ const distance = viewport.scrollHeight - viewport.clientHeight - viewport.scrollTop;
46
+ changeFollowing(distance <= threshold);
47
+ };
48
+ const observer = typeof ResizeObserver === "undefined" ? void 0 : new ResizeObserver(followGrowth);
49
+ observer?.observe(content);
50
+ observer?.observe(viewport);
51
+ viewport.addEventListener("scroll", onScroll);
52
+ followGrowth();
53
+ return () => {
54
+ cancelAnimationFrame(frame);
55
+ observer?.disconnect();
56
+ viewport.removeEventListener("scroll", onScroll);
57
+ };
58
+ }, [
59
+ threshold,
60
+ changeFollowing
61
+ ]);
62
+ return {
63
+ viewportRef,
64
+ contentRef,
65
+ following,
66
+ scrollToEnd
67
+ };
68
+ };
69
+
70
+ // src/follow-scroll/follow-scroll.tsx
71
+ import { Button } from "@gridui/button";
72
+ import { cn } from "@gridui/style-utils";
73
+ import { jsx, jsxs } from "react/jsx-runtime";
74
+ var FollowScroll = (props) => {
75
+ const { label, jumpLabel, threshold, onFollowingChange, children, className, ...restProps } = props;
76
+ const { viewportRef, contentRef, following, scrollToEnd } = useFollowScroll({
77
+ ...threshold === void 0 ? {} : { threshold },
78
+ ...onFollowingChange === void 0 ? {} : { onFollowingChange }
79
+ });
80
+ return /* @__PURE__ */ jsxs(
81
+ "div",
82
+ {
83
+ ...restProps,
84
+ className: cn("gridui-follow-scroll", className),
85
+ children: [
86
+ /* @__PURE__ */ jsx(
87
+ "div",
88
+ {
89
+ ref: viewportRef,
90
+ className: "gridui-follow-scroll-viewport",
91
+ role: "region",
92
+ "aria-label": label,
93
+ tabIndex: 0,
94
+ children: /* @__PURE__ */ jsx(
95
+ "div",
96
+ {
97
+ ref: contentRef,
98
+ className: "gridui-follow-scroll-content",
99
+ children
100
+ }
101
+ )
102
+ }
103
+ ),
104
+ !following && /* @__PURE__ */ jsx(
105
+ Button,
106
+ {
107
+ className: "gridui-follow-scroll-jump",
108
+ size: "small",
109
+ onClick: () => {
110
+ scrollToEnd();
111
+ viewportRef.current?.focus({ preventScroll: true });
112
+ },
113
+ children: jumpLabel
114
+ }
115
+ )
116
+ ]
117
+ }
118
+ );
119
+ };
120
+ export {
121
+ FollowScroll,
122
+ useFollowScroll
123
+ };
124
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1,7 @@
1
+ {
2
+ "version": 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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",
6
+ "names": []
7
+ }
@@ -0,0 +1,26 @@
1
+ /*! tailwindcss v4.3.3 | MIT License | https://tailwindcss.com */
2
+ @layer theme, base, components, utilities;
3
+ @layer utilities;
4
+ @layer components {
5
+ .gridui-follow-scroll {
6
+ position: relative;
7
+ display: flex;
8
+ flex-direction: column;
9
+ min-height: 0;
10
+ }
11
+ .gridui-follow-scroll-viewport {
12
+ flex: 1;
13
+ min-height: 0;
14
+ overflow: auto;
15
+ overscroll-behavior: contain;
16
+ overflow-anchor: none;
17
+ }
18
+ .gridui-follow-scroll-content {
19
+ display: flow-root;
20
+ }
21
+ .gridui-follow-scroll-jump {
22
+ align-self: center;
23
+ flex: none;
24
+ margin: 8px;
25
+ }
26
+ }
package/package.json CHANGED
@@ -1,6 +1,51 @@
1
1
  {
2
2
  "name": "@gridui/follow-scroll",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.0.0",
4
+ "description": "GridUI React follow scroll",
5
+ "license": "UNLICENSED",
6
+ "type": "module",
7
+ "files": [
8
+ "dist",
9
+ "README.md"
10
+ ],
11
+ "sideEffects": [
12
+ "**/*.css"
13
+ ],
14
+ "exports": {
15
+ ".": {
16
+ "types": "./dist/index.d.ts",
17
+ "import": "./dist/index.js"
18
+ },
19
+ "./styles.css": "./dist/styles.css"
20
+ },
21
+ "publishConfig": {
22
+ "access": "public"
23
+ },
24
+ "peerDependencies": {
25
+ "react": "^19.2.0",
26
+ "react-dom": "^19.2.0"
27
+ },
28
+ "dependencies": {
29
+ "@gridui/button": "^2.1.1",
30
+ "@gridui/style-utils": "^2.1.2",
31
+ "@gridui/theme": "^2.1.2"
32
+ },
33
+ "devDependencies": {
34
+ "@gridui-internal/configuration": "0.0.0",
35
+ "@jest/globals": "30.5.2",
36
+ "@types/jest": "30.0.0",
37
+ "@types/node": "26.6.5",
38
+ "@types/react": "19.3.0",
39
+ "@types/react-dom": "19.3.0",
40
+ "jest": "30.5.2",
41
+ "react": "19.3.1",
42
+ "react-dom": "19.3.1",
43
+ "typescript": "6.0.3"
44
+ },
45
+ "scripts": {
46
+ "build": "node ../../scripts/compilation/package.ts",
47
+ "compile": "tsc --project tsconfig.json",
48
+ "test": "jest --passWithNoTests",
49
+ "coverage": "jest --coverage --passWithNoTests"
50
+ }
6
51
  }