@lynx-js/lynx-ui-scroll-coordinator 0.0.0-oidc-bootstrap.0 → 3.142.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/LICENSE CHANGED
@@ -198,4 +198,4 @@
198
198
  distributed under the License is distributed on an "AS IS" BASIS,
199
199
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
200
  See the License for the specific language governing permissions and
201
- limitations under the License.
201
+ limitations under the License.
package/README.md CHANGED
@@ -1,9 +1,24 @@
1
1
  # @lynx-js/lynx-ui-scroll-coordinator
2
2
 
3
- > Placeholder package published only to enable npm Trusted Publishing (OIDC) setup.
3
+ A headless collapsible header that coordinates scrolling with nested lists, scroll views, and paged content in ReactLynx.
4
4
 
5
- This is a placeholder package published only to enable npm Trusted Publishing (OIDC) setup.
5
+ ## Installation
6
6
 
7
- It contains no functional code and should not be installed.
7
+ ```bash
8
+ pnpm add @lynx-js/lynx-ui
9
+ ```
8
10
 
9
- A proper release will replace this package once OIDC is configured.
11
+ The standalone package is also available as `@lynx-js/lynx-ui-scroll-coordinator`.
12
+
13
+ ## Structure
14
+
15
+ `ScrollCoordinator` combines a collapsible `headers` region, a persistent `toolbar`, and a scrollable `slot`. It supports outer and per-page pull-to-refresh, offset callbacks on both threads, and imperative header navigation.
16
+
17
+ - [Examples](../../apps/examples/ScrollCoordinator)
18
+ - [ViewPager with a List in each page](../../apps/examples/ScrollCoordinator/ViewPagerList)
19
+ - [API reference](./docs/APIReference.mdx)
20
+ - [Component guidance](./SKILL.md)
21
+
22
+ ## License
23
+
24
+ [Apache License 2.0](./LICENSE)
@@ -0,0 +1,5 @@
1
+ import type { ScrollCoordinatorProps, ScrollCoordinatorRef } from './types/index.js';
2
+ import './styles.css';
3
+ export type * from './types/index.js';
4
+ export declare const ScrollCoordinator: import("react").MemoExoticComponent<import("react").ForwardRefExoticComponent<ScrollCoordinatorProps & import("react").RefAttributes<ScrollCoordinatorRef>>>;
5
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,sBAAsB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAC3E,OAAO,cAAc,CAAA;AAIrB,mBAAmB,SAAS,CAAA;AAE5B,eAAO,MAAM,iBAAiB,8JAA0C,CAAA"}
package/dist/index.jsx ADDED
@@ -0,0 +1,140 @@
1
+ import { forwardRef, memo, useImperativeHandle, useRef, useState } from "@lynx-js/react";
2
+ import { getRectById, getRectByRef } from "@lynx-js/lynx-ui-common";
3
+ import { clsx } from "clsx";
4
+ import "./styles.css";
5
+ const ScrollCoordinator = memo(forwardRef(ScrollCoordinatorImpl));
6
+ function ScrollCoordinatorImpl(props, ref) {
7
+ const { id, className, style, coordinatorProps, headers, toolbar, slot, refreshOptions = false, bounces = false, enableScroll = true, refreshInSlot = false, scrollBarEnable = false, headerOverSlot = false, granularity = 0.01, popupOptions, scrollWithNative = false, onOffsetChange, 'main-thread:onOffsetChange': onOffsetChangeMT, 'main-thread:gesture': gesture, onSticky, onLeaveSticky } = props;
8
+ const nativeRef = useRef(null);
9
+ const headerRef = useRef(null);
10
+ const refreshRef = useRef(null);
11
+ const refreshHeaderSize = useRef(0);
12
+ const refreshOffset = useRef(0);
13
+ const stickyRef = useRef(false);
14
+ const [isSticky, setSticky] = useState(false);
15
+ const refreshProps = refreshOptions || void 0;
16
+ const hasRefresh = void 0 !== refreshProps;
17
+ const enableRefresh = refreshProps?.enableRefresh ?? false;
18
+ const scrollTo = (offset, animated, success, fail)=>{
19
+ nativeRef.current?.invoke({
20
+ method: 'setFoldExpanded',
21
+ params: {
22
+ offset,
23
+ smooth: animated
24
+ },
25
+ success,
26
+ fail
27
+ }).exec();
28
+ };
29
+ useImperativeHandle(ref, ()=>({
30
+ startRefresh () {
31
+ if (!enableRefresh) return;
32
+ refreshRef.current?.invoke({
33
+ method: 'autoStartRefresh'
34
+ }).exec();
35
+ },
36
+ finishRefresh () {
37
+ refreshRef.current?.invoke({
38
+ method: 'finishRefresh'
39
+ }).exec();
40
+ },
41
+ scrollTo,
42
+ scrollToTop (animated, success, fail) {
43
+ scrollTo('0px', animated, success, fail);
44
+ },
45
+ scrollToSticky (animated, success, fail) {
46
+ scrollTo('99999999px', animated, success, fail);
47
+ },
48
+ scrollIntoView (targetId, animated, success, fail) {
49
+ Promise.all([
50
+ getRectById(targetId),
51
+ getRectByRef(headerRef)
52
+ ]).then(([target, header])=>scrollTo(`${target.top - header.top}px`, animated, success, fail)).catch((error)=>fail?.(error));
53
+ }
54
+ }));
55
+ const bindOffset = (event)=>{
56
+ const { offset, height } = event.detail;
57
+ onOffsetChange?.({
58
+ offset,
59
+ height
60
+ });
61
+ const sticky = height > 0 && offset / height >= 1 - granularity;
62
+ if (sticky === stickyRef.current) return;
63
+ stickyRef.current = sticky;
64
+ setSticky(sticky);
65
+ if (sticky) onSticky?.();
66
+ else onLeaveSticky?.();
67
+ };
68
+ const handleOffsetMT = (event)=>{
69
+ 'main thread';
70
+ const { offset, height } = event.detail;
71
+ onOffsetChangeMT?.({
72
+ offset,
73
+ height
74
+ });
75
+ };
76
+ const handleRefreshHeaderLayout = (event)=>{
77
+ refreshHeaderSize.current = event.detail.height;
78
+ };
79
+ const handleRefreshOffset = (event)=>{
80
+ const headerSize = refreshHeaderSize.current;
81
+ const offset = event.detail.offsetPercent * headerSize;
82
+ refreshOffset.current = offset;
83
+ refreshProps?.onRefreshOffsetChange?.({
84
+ offset,
85
+ headerSize,
86
+ isDragging: event.detail.isDragging
87
+ });
88
+ };
89
+ const handleStartRefresh = (event)=>{
90
+ if (!enableRefresh) return;
91
+ refreshProps?.onStartRefresh?.({
92
+ triggeredBy: event.detail.isManual ? 'drag' : 'startRefresh'
93
+ });
94
+ };
95
+ const refreshViewProps = {
96
+ bindheaderreleased: ()=>{
97
+ refreshProps?.onHeaderReleased?.({
98
+ offset: refreshOffset.current,
99
+ headerSize: refreshHeaderSize.current
100
+ });
101
+ }
102
+ };
103
+ const coordinator = <scroll-coordinator {...coordinatorProps} ref={nativeRef} id={id} className={clsx('lynx-ui-scroll-coordinator__root', {
104
+ 'ui-sticky': isSticky
105
+ }, !hasRefresh && className)} style={hasRefresh ? void 0 : style} granularity={granularity} {...gesture ? {
106
+ 'main-thread:gesture': gesture
107
+ } : {}} bounces={popupOptions?.enableHalfToFullScreen ? false : enableRefresh || bounces} android-enable-touch-stop-fling={true} enable-scroll={enableScroll} enable-scroll-bar={scrollBarEnable} header-over-slot={headerOverSlot} refresh-mode={enableRefresh ? 'fold' : refreshInSlot ? 'page' : 'none'} bindoffset={bindOffset} {...onOffsetChangeMT ? {
108
+ 'main-thread:bindoffset': handleOffsetMT
109
+ } : {}} name={popupOptions?.name} compat-container-popup={Boolean(popupOptions?.enableHalfToFullScreen)} android-nested-scroll-as-child={scrollWithNative}>
110
+ {null != toolbar && <scroll-coordinator-toolbar className='lynx-ui-scroll-coordinator__toolbar'>
111
+ {toolbar}
112
+ </scroll-coordinator-toolbar>}
113
+ <scroll-coordinator-header ref={headerRef} id={id ? `${id}-header` : void 0} className='lynx-ui-scroll-coordinator__header' style={hasRefresh ? {
114
+ minHeight: '1px'
115
+ } : {
116
+ height: 'max-content'
117
+ }}>
118
+ {headers}
119
+ </scroll-coordinator-header>
120
+ <scroll-coordinator-slot className='lynx-ui-scroll-coordinator__slot'>
121
+ {slot}
122
+ </scroll-coordinator-slot>
123
+ </scroll-coordinator>;
124
+ if (!hasRefresh) return coordinator;
125
+ return <refresh {...refreshViewProps} ref={refreshRef} id={id ? `${id}-refresh` : void 0} className={clsx('lynx-ui-scroll-coordinator__refresh', className, {
126
+ 'ui-sticky': isSticky
127
+ })} style={style} enable-refresh={enableRefresh} enable-loadmore={false} detect-scrollchild={true} bindstartrefresh={handleStartRefresh} bindheaderoffset={handleRefreshOffset} bindrefreshstatechange={(event)=>{
128
+ refreshProps?.onRefreshStateChange?.({
129
+ state: event.detail.state
130
+ });
131
+ }}>
132
+ <refresh-header className='lynx-ui-scroll-coordinator__refresh-header' bindlayoutchange={handleRefreshHeaderLayout}>
133
+ {refreshProps.headerContent}
134
+ </refresh-header>
135
+ {coordinator}
136
+ </refresh>;
137
+ }
138
+ export { ScrollCoordinator };
139
+
140
+ //# sourceMappingURL=index.jsx.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.jsx","sources":["../src/index.tsx"],"sourcesContent":["// Copyright 2026 The Lynx Authors. All rights reserved.\n// Licensed under the Apache License Version 2.0 that can be found in the\n// LICENSE file in the root directory of this source tree.\n\nimport {\n forwardRef,\n memo,\n useImperativeHandle,\n useRef,\n useState,\n} from '@lynx-js/react'\nimport type { ForwardedRef } from '@lynx-js/react'\n\nimport { getRectById, getRectByRef } from '@lynx-js/lynx-ui-common'\nimport type {\n LayoutChangeEvent,\n NodesRef,\n RefreshHeaderOffsetEvent,\n RefreshStartRefreshEvent,\n RefreshStateChangeEvent,\n ScrollCoordinatorOffsetEvent,\n} from '@lynx-js/types'\nimport { clsx } from 'clsx'\n\nimport type { ScrollCoordinatorProps, ScrollCoordinatorRef } from './types'\nimport './styles.css'\n\n// cspell:ignore bindoffset bindstartrefresh bindheaderoffset bindheaderreleased bindrefreshstatechange scrollchild\n\nexport type * from './types'\n\nexport const ScrollCoordinator = memo(forwardRef(ScrollCoordinatorImpl))\n\nfunction ScrollCoordinatorImpl(\n props: ScrollCoordinatorProps,\n ref: ForwardedRef<ScrollCoordinatorRef>,\n) {\n const {\n id,\n className,\n style,\n coordinatorProps,\n headers,\n toolbar,\n slot,\n refreshOptions = false,\n bounces = false,\n enableScroll = true,\n refreshInSlot = false,\n scrollBarEnable = false,\n headerOverSlot = false,\n granularity = 0.01,\n popupOptions,\n scrollWithNative = false,\n onOffsetChange,\n 'main-thread:onOffsetChange': onOffsetChangeMT,\n 'main-thread:gesture': gesture,\n onSticky,\n onLeaveSticky,\n } = props\n const nativeRef = useRef<NodesRef>(null)\n const headerRef = useRef<NodesRef>(null)\n const refreshRef = useRef<NodesRef>(null)\n const refreshHeaderSize = useRef(0)\n const refreshOffset = useRef(0)\n const stickyRef = useRef(false)\n const [isSticky, setSticky] = useState(false)\n const refreshProps = refreshOptions || undefined\n const hasRefresh = refreshProps !== undefined\n const enableRefresh = refreshProps?.enableRefresh ?? false\n\n const scrollTo: ScrollCoordinatorRef['scrollTo'] = (\n offset,\n animated,\n success,\n fail,\n ) => {\n nativeRef.current?.invoke({\n method: 'setFoldExpanded',\n params: { offset, smooth: animated },\n success,\n fail,\n }).exec()\n }\n\n useImperativeHandle(ref, () => ({\n startRefresh() {\n if (!enableRefresh) return\n refreshRef.current?.invoke({ method: 'autoStartRefresh' }).exec()\n },\n finishRefresh() {\n refreshRef.current?.invoke({ method: 'finishRefresh' }).exec()\n },\n scrollTo,\n scrollToTop(animated, success, fail) {\n scrollTo('0px', animated, success, fail)\n },\n scrollToSticky(animated, success, fail) {\n // The native method clamps the requested offset to the header's range.\n scrollTo('99999999px', animated, success, fail)\n },\n scrollIntoView(targetId, animated, success, fail) {\n Promise.all([getRectById(targetId), getRectByRef(headerRef)])\n .then(([target, header]) =>\n scrollTo(`${target.top - header.top}px`, animated, success, fail)\n )\n .catch((error: unknown) => fail?.(error))\n },\n }))\n\n const bindOffset = (event: ScrollCoordinatorOffsetEvent) => {\n const { offset, height } = event.detail\n onOffsetChange?.({ offset, height })\n const sticky = height > 0 && offset / height >= 1 - granularity\n if (sticky === stickyRef.current) return\n // Native events can arrive before React commits the next render.\n stickyRef.current = sticky\n setSticky(sticky)\n if (sticky) onSticky?.()\n else onLeaveSticky?.()\n }\n\n const handleOffsetMT = (event: ScrollCoordinatorOffsetEvent) => {\n 'main thread'\n const { offset, height } = event.detail\n onOffsetChangeMT?.({ offset, height })\n }\n\n const handleRefreshHeaderLayout = (event: LayoutChangeEvent) => {\n refreshHeaderSize.current = event.detail.height\n }\n\n const handleRefreshOffset = (event: RefreshHeaderOffsetEvent) => {\n const headerSize = refreshHeaderSize.current\n const offset = event.detail.offsetPercent * headerSize\n refreshOffset.current = offset\n refreshProps?.onRefreshOffsetChange?.({\n offset,\n headerSize,\n isDragging: event.detail.isDragging,\n })\n }\n\n const handleStartRefresh = (event: RefreshStartRefreshEvent) => {\n if (!enableRefresh) return\n refreshProps?.onStartRefresh?.({\n triggeredBy: event.detail.isManual ? 'drag' : 'startRefresh',\n })\n }\n\n // The native release event is not yet declared in the public element types.\n const refreshViewProps = {\n bindheaderreleased: () => {\n refreshProps?.onHeaderReleased?.({\n offset: refreshOffset.current,\n headerSize: refreshHeaderSize.current,\n })\n },\n }\n\n const coordinator = (\n <scroll-coordinator\n {...coordinatorProps}\n ref={nativeRef}\n id={id}\n className={clsx('lynx-ui-scroll-coordinator__root', {\n 'ui-sticky': isSticky,\n }, !hasRefresh && className)}\n style={hasRefresh ? undefined : style}\n granularity={granularity}\n {...(gesture ? { 'main-thread:gesture': gesture } : {})}\n bounces={popupOptions?.enableHalfToFullScreen\n ? false\n : enableRefresh || bounces}\n android-enable-touch-stop-fling={true}\n enable-scroll={enableScroll}\n enable-scroll-bar={scrollBarEnable}\n header-over-slot={headerOverSlot}\n refresh-mode={enableRefresh ? 'fold' : (refreshInSlot ? 'page' : 'none')}\n bindoffset={bindOffset}\n {...(onOffsetChangeMT\n ? { 'main-thread:bindoffset': handleOffsetMT }\n : {})}\n name={popupOptions?.name}\n compat-container-popup={Boolean(popupOptions?.enableHalfToFullScreen)}\n android-nested-scroll-as-child={scrollWithNative}\n >\n {toolbar != null && (\n <scroll-coordinator-toolbar className='lynx-ui-scroll-coordinator__toolbar'>\n {toolbar}\n </scroll-coordinator-toolbar>\n )}\n <scroll-coordinator-header\n ref={headerRef}\n id={id ? `${id}-header` : undefined}\n className='lynx-ui-scroll-coordinator__header'\n style={hasRefresh ? { minHeight: '1px' } : { height: 'max-content' }}\n >\n {headers}\n </scroll-coordinator-header>\n <scroll-coordinator-slot className='lynx-ui-scroll-coordinator__slot'>\n {slot}\n </scroll-coordinator-slot>\n </scroll-coordinator>\n )\n\n if (!hasRefresh) return coordinator\n\n return (\n <refresh\n {...refreshViewProps}\n ref={refreshRef}\n id={id ? `${id}-refresh` : undefined}\n className={clsx('lynx-ui-scroll-coordinator__refresh', className, {\n 'ui-sticky': isSticky,\n })}\n style={style}\n enable-refresh={enableRefresh}\n enable-loadmore={false}\n detect-scrollchild={true}\n bindstartrefresh={handleStartRefresh}\n bindheaderoffset={handleRefreshOffset}\n bindrefreshstatechange={(event: RefreshStateChangeEvent) => {\n refreshProps?.onRefreshStateChange?.({ state: event.detail.state })\n }}\n >\n <refresh-header\n className='lynx-ui-scroll-coordinator__refresh-header'\n bindlayoutchange={handleRefreshHeaderLayout}\n >\n {refreshProps.headerContent}\n </refresh-header>\n {coordinator}\n </refresh>\n )\n}\n"],"names":["ScrollCoordinator","memo","forwardRef","ScrollCoordinatorImpl","props","ref","id","className","style","coordinatorProps","headers","toolbar","slot","refreshOptions","bounces","enableScroll","refreshInSlot","scrollBarEnable","headerOverSlot","granularity","popupOptions","scrollWithNative","onOffsetChange","onOffsetChangeMT","gesture","onSticky","onLeaveSticky","nativeRef","useRef","headerRef","refreshRef","refreshHeaderSize","refreshOffset","stickyRef","isSticky","setSticky","useState","refreshProps","undefined","hasRefresh","enableRefresh","scrollTo","offset","animated","success","fail","useImperativeHandle","targetId","Promise","getRectById","getRectByRef","target","header","error","bindOffset","event","height","sticky","handleOffsetMT","handleRefreshHeaderLayout","handleRefreshOffset","headerSize","handleStartRefresh","refreshViewProps","coordinator","scroll-coordinator","clsx","Boolean","scroll-coordinator-toolbar","scroll-coordinator-header","scroll-coordinator-slot","refresh","refresh-header"],"mappings":"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"}
@@ -0,0 +1,46 @@
1
+ .lynx-ui-scroll-coordinator__refresh {
2
+ width: 100%;
3
+ height: 100%;
4
+ display: flex;
5
+ }
6
+
7
+ .lynx-ui-scroll-coordinator__refresh-header {
8
+ width: 100%;
9
+ position: absolute;
10
+ overflow: visible;
11
+ }
12
+
13
+ .lynx-ui-scroll-coordinator__root {
14
+ z-index: 0;
15
+ flex-direction: column;
16
+ width: 100%;
17
+ height: 100%;
18
+ display: flex;
19
+ overflow: visible;
20
+ }
21
+
22
+ .lynx-ui-scroll-coordinator__header {
23
+ z-index: 1;
24
+ width: 100%;
25
+ position: absolute;
26
+ overflow: visible;
27
+ }
28
+
29
+ .lynx-ui-scroll-coordinator__toolbar {
30
+ z-index: 2;
31
+ width: 100%;
32
+ display: flex;
33
+ overflow: visible;
34
+ }
35
+
36
+ .lynx-ui-scroll-coordinator__slot {
37
+ z-index: 1;
38
+ flex-direction: column;
39
+ flex: 1;
40
+ width: 100%;
41
+ display: flex;
42
+ overflow: visible;
43
+ }
44
+
45
+
46
+ /*# sourceMappingURL=styles.css.map */
@@ -0,0 +1 @@
1
+ {"version":3,"sources":["webpack://./src/styles.css"],"names":[],"mappings":"AAAA;EACE,WAAW;EACX,YAAY;EACZ,aAAa;AACf;;AAEA;EACE,WAAW;EACX,kBAAkB;EAClB,iBAAiB;AACnB;;AAEA;EACE,UAAU;EACV,sBAAsB;EACtB,WAAW;EACX,YAAY;EACZ,aAAa;EACb,iBAAiB;AACnB;;AAEA;EACE,UAAU;EACV,WAAW;EACX,kBAAkB;EAClB,iBAAiB;AACnB;;AAEA;EACE,UAAU;EACV,WAAW;EACX,aAAa;EACb,iBAAiB;AACnB;;AAEA;EACE,UAAU;EACV,sBAAsB;EACtB,OAAO;EACP,WAAW;EACX,aAAa;EACb,iBAAiB;AACnB","sourcesContent":[".lynx-ui-scroll-coordinator__refresh {\n display: flex;\n width: 100%;\n height: 100%;\n}\n\n.lynx-ui-scroll-coordinator__refresh-header {\n width: 100%;\n position: absolute;\n overflow: visible;\n}\n\n.lynx-ui-scroll-coordinator__root {\n width: 100%;\n height: 100%;\n z-index: 0;\n display: flex;\n flex-direction: column;\n overflow: visible;\n}\n\n.lynx-ui-scroll-coordinator__header {\n position: absolute;\n width: 100%;\n z-index: 1;\n overflow: visible;\n}\n\n.lynx-ui-scroll-coordinator__toolbar {\n width: 100%;\n display: flex;\n z-index: 2;\n overflow: visible;\n}\n\n.lynx-ui-scroll-coordinator__slot {\n display: flex;\n flex-direction: column;\n width: 100%;\n flex: 1;\n z-index: 1;\n overflow: visible;\n}\n"],"sourceRoot":""}
@@ -0,0 +1,2 @@
1
+ export type * from './index.docs.js';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAIA,mBAAmB,cAAc,CAAA"}
@@ -0,0 +1,241 @@
1
+ import type { ReactNode } from '@lynx-js/react';
2
+ import type { BaseGesture } from '@lynx-js/gesture-runtime';
3
+ import type { ComponentBasicProps } from '@lynx-js/lynx-ui-common';
4
+ import type { ScrollCoordinatorProps as NativeScrollCoordinatorProps, ScrollCoordinatorOffset } from '@lynx-js/types';
5
+ export type { ScrollCoordinatorOffset };
6
+ export interface ScrollCoordinatorRef {
7
+ /**
8
+ * Start the outer refresh through its native node. Requires enableRefresh.
9
+ * onStartRefresh reports triggeredBy: 'startRefresh'. Does not control slot refresh instances.
10
+ * @Android
11
+ * @iOS
12
+ */
13
+ startRefresh: () => void;
14
+ /**
15
+ * End the outer refresh, including after a failed request. An existing refresh
16
+ * can still finish after enableRefresh becomes false. Does not reset list offsets.
17
+ * @Android
18
+ * @iOS
19
+ */
20
+ finishRefresh: () => void;
21
+ /**
22
+ * Expand the header. Does not reset the nested list's own scroll position.
23
+ * @Android
24
+ * @iOS
25
+ */
26
+ scrollToTop: (animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void;
27
+ /**
28
+ * Collapse the header to its sticky position.
29
+ * @Android
30
+ * @iOS
31
+ */
32
+ scrollToSticky: (animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void;
33
+ /**
34
+ * Set the header offset. The native coordinator clamps it to the scrollable range.
35
+ * @Android
36
+ * @iOS
37
+ */
38
+ scrollTo: (offset: `${number}px` | `${number}rpx`, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void;
39
+ /**
40
+ * Scroll to an element inside headers, measured relative to this instance's header.
41
+ * @Android
42
+ * @iOS
43
+ */
44
+ scrollIntoView: (id: string, animated: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void;
45
+ }
46
+ export interface ScrollCoordinatorUIVariants {
47
+ /**
48
+ * Applied to the coordinator and outer refresh wrapper while the header is collapsed.
49
+ * @zh 头部折叠时,应用于协调器和外层刷新容器。
50
+ */
51
+ 'ui-sticky'?: boolean;
52
+ }
53
+ /** Native refresh options with the same callback shapes as FeedList. */
54
+ export interface ScrollCoordinatorRefreshOptions {
55
+ /**
56
+ * Allow pull gestures and startRefresh() to start the outer refresh.
57
+ * Toggle this flag to preserve the mounted content and its scroll position.
58
+ * @Android
59
+ * @iOS
60
+ */
61
+ enableRefresh: boolean;
62
+ /**
63
+ * Refresh header content. Give it a nonzero height to define the pull threshold.
64
+ * Keep its dimensions stable while refreshing to avoid resetting the native header position.
65
+ * @Android
66
+ * @iOS
67
+ */
68
+ headerContent: ReactNode;
69
+ /**
70
+ * Start loading data. Always call ref.finishRefresh() when the request settles.
71
+ * Returning a Promise does not automatically end the refresh.
72
+ * @Android
73
+ * @iOS
74
+ */
75
+ onStartRefresh?: (event: {
76
+ triggeredBy: 'startRefresh' | 'drag';
77
+ }) => void;
78
+ /**
79
+ * Pull offset and measured header height in px. The height is zero until layout.
80
+ * Progress is offset / headerSize when headerSize > 0, and may exceed 1.
81
+ * @Android
82
+ * @iOS
83
+ */
84
+ onRefreshOffsetChange?: (event: {
85
+ offset: number;
86
+ headerSize: number;
87
+ isDragging: boolean;
88
+ }) => void;
89
+ /**
90
+ * Native state: 0 idle, 1 released past the threshold, 2 refreshing.
91
+ * Event order is platform-dependent. Use isDragging from the offset event for drag state.
92
+ * @Android
93
+ * @iOS
94
+ */
95
+ onRefreshStateChange?: (event: {
96
+ state: number;
97
+ }) => void;
98
+ /**
99
+ * The native header was released. Reports the latest offset and measured height in px.
100
+ * @Android
101
+ * @iOS
102
+ */
103
+ onHeaderReleased?: (event: {
104
+ offset: number;
105
+ headerSize: number;
106
+ }) => void;
107
+ }
108
+ /** Coordinates a collapsible header with nested vertical lists or scroll views. */
109
+ export interface ScrollCoordinatorProps extends ComponentBasicProps {
110
+ /**
111
+ * Optional native coordinator ID. Imperative methods use instance-local node refs.
112
+ * @Android
113
+ * @iOS
114
+ */
115
+ id?: string;
116
+ /**
117
+ * Collapsible header content.
118
+ * @Android
119
+ * @iOS
120
+ */
121
+ headers?: ReactNode;
122
+ /**
123
+ * Persistent toolbar. Its height is subtracted from the header's collapse range.
124
+ * @Android
125
+ * @iOS
126
+ */
127
+ toolbar?: ReactNode;
128
+ /**
129
+ * Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
130
+ * @Android
131
+ * @iOS
132
+ */
133
+ slot?: ReactNode;
134
+ /**
135
+ * Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot.
136
+ * Providing an options object mounts the refresh wrapper, even while enableRefresh is false.
137
+ * className and style apply to this wrapper; otherwise they apply to the native coordinator.
138
+ * No implementation mode is required. @defaultValue false
139
+ * @Android
140
+ * @iOS
141
+ */
142
+ refreshOptions?: false | ScrollCoordinatorRefreshOptions;
143
+ /**
144
+ * Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it. @defaultValue false
145
+ * @iOS
146
+ */
147
+ bounces?: boolean;
148
+ /**
149
+ * Enable vertical coordinator scrolling. @defaultValue true
150
+ * @Android
151
+ * @iOS
152
+ */
153
+ enableScroll?: boolean;
154
+ /**
155
+ * Place the overflowing header above the slot. @defaultValue false
156
+ * @Android
157
+ * @iOS
158
+ */
159
+ headerOverSlot?: boolean;
160
+ /**
161
+ * Use independent refresh elements inside the slot. Each nested refresh must
162
+ * finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
163
+ * @defaultValue false
164
+ * @Android
165
+ * @iOS
166
+ */
167
+ refreshInSlot?: boolean;
168
+ /**
169
+ * Show the coordinator scrollbar on supported platforms. @defaultValue false
170
+ * @Android
171
+ * @iOS
172
+ */
173
+ scrollBarEnable?: boolean;
174
+ /**
175
+ * Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold. @defaultValue 0.01
176
+ * @Android
177
+ * @iOS
178
+ */
179
+ granularity?: number;
180
+ /**
181
+ * Native host popup integration for hosts that support half-to-full-screen expansion.
182
+ * @Android
183
+ * @iOS
184
+ */
185
+ popupOptions?: {
186
+ /**
187
+ * Name identifying the coordinator to the native popup container.
188
+ * @Android
189
+ * @iOS
190
+ */
191
+ name: string;
192
+ /**
193
+ * Enable native popup coordination and disable bounce.
194
+ * @Android
195
+ * @iOS
196
+ */
197
+ enableHalfToFullScreen: boolean;
198
+ };
199
+ /**
200
+ * Participate as a nested scrolling child of a native Android container. @defaultValue false
201
+ * @Android
202
+ */
203
+ scrollWithNative?: boolean;
204
+ /**
205
+ * Native gesture attached to the coordinator.
206
+ * @Android
207
+ * @iOS
208
+ */
209
+ 'main-thread:gesture'?: BaseGesture;
210
+ /**
211
+ * Native properties passed explicitly to the coordinator. Managed properties take precedence.
212
+ * @Android
213
+ * @iOS
214
+ */
215
+ coordinatorProps?: Omit<NativeScrollCoordinatorProps, 'ref' | 'children' | 'id' | 'style' | 'className'>;
216
+ /**
217
+ * Header offset and total collapse range, in px.
218
+ * @Android
219
+ * @iOS
220
+ */
221
+ onOffsetChange?: (event: ScrollCoordinatorOffset) => void;
222
+ /**
223
+ * Header offset callback on the main thread. Pass a function with the 'main thread' directive.
224
+ * @Android
225
+ * @iOS
226
+ */
227
+ 'main-thread:onOffsetChange'?: (event: ScrollCoordinatorOffset) => void;
228
+ /**
229
+ * Called once when the header reaches the sticky threshold.
230
+ * @Android
231
+ * @iOS
232
+ */
233
+ onSticky?: () => void;
234
+ /**
235
+ * Called once when the header leaves the sticky threshold.
236
+ * @Android
237
+ * @iOS
238
+ */
239
+ onLeaveSticky?: () => void;
240
+ }
241
+ //# sourceMappingURL=index.docs.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.docs.d.ts","sourceRoot":"","sources":["../../src/types/index.docs.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1 @@
1
+ export { };
@@ -0,0 +1 @@
1
+ export { };
package/package.json CHANGED
@@ -1,14 +1,53 @@
1
1
  {
2
2
  "name": "@lynx-js/lynx-ui-scroll-coordinator",
3
- "version": "0.0.0-oidc-bootstrap.0",
4
- "description": "Placeholder package published only to enable npm Trusted Publishing (OIDC) setup.",
3
+ "version": "3.142.0",
4
+ "repository": {
5
+ "type": "git",
6
+ "url": "git+https://github.com/lynx-family/lynx-ui.git",
7
+ "directory": "packages/lynx-ui-scroll-coordinator"
8
+ },
5
9
  "license": "Apache-2.0",
6
- "author": "The Lynx Authors",
10
+ "author": {
11
+ "name": "The Lynx Authors"
12
+ },
13
+ "sideEffects": false,
14
+ "type": "module",
15
+ "main": "./dist/index.jsx",
16
+ "module": "./dist/index.jsx",
17
+ "types": "./dist/index.d.ts",
7
18
  "files": [
19
+ "src/**",
8
20
  "README.md",
9
- "LICENSE"
21
+ "LICENSE",
22
+ "tsconfig.docs.json",
23
+ "tsconfig.json",
24
+ "dist/**"
10
25
  ],
26
+ "dependencies": {
27
+ "@lynx-js/gesture-runtime": "2.1.1",
28
+ "clsx": "^2.1.1",
29
+ "@lynx-js/lynx-ui-common": "3.142.0"
30
+ },
31
+ "devDependencies": {
32
+ "@lynx-js/react": "0.123.1",
33
+ "@lynx-js/types": "4.1.0",
34
+ "@rslib/core": "0.23.2",
35
+ "@types/react": "^18.3.8",
36
+ "jsdom": "^25.0.1",
37
+ "typescript": "^5.8.0"
38
+ },
39
+ "peerDependencies": {
40
+ "@lynx-js/react": ">=0.100.0",
41
+ "@lynx-js/types": "*",
42
+ "@types/react": ">=18"
43
+ },
11
44
  "publishConfig": {
12
45
  "access": "public"
46
+ },
47
+ "jsnext:source": "./src/index.tsx",
48
+ "scripts": {
49
+ "build": "rslib build",
50
+ "build:watch": "rslib build --watch",
51
+ "test": "vitest"
13
52
  }
14
- }
53
+ }
package/src/index.tsx ADDED
@@ -0,0 +1,236 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import {
6
+ forwardRef,
7
+ memo,
8
+ useImperativeHandle,
9
+ useRef,
10
+ useState,
11
+ } from '@lynx-js/react'
12
+ import type { ForwardedRef } from '@lynx-js/react'
13
+
14
+ import { getRectById, getRectByRef } from '@lynx-js/lynx-ui-common'
15
+ import type {
16
+ LayoutChangeEvent,
17
+ NodesRef,
18
+ RefreshHeaderOffsetEvent,
19
+ RefreshStartRefreshEvent,
20
+ RefreshStateChangeEvent,
21
+ ScrollCoordinatorOffsetEvent,
22
+ } from '@lynx-js/types'
23
+ import { clsx } from 'clsx'
24
+
25
+ import type { ScrollCoordinatorProps, ScrollCoordinatorRef } from './types'
26
+ import './styles.css'
27
+
28
+ // cspell:ignore bindoffset bindstartrefresh bindheaderoffset bindheaderreleased bindrefreshstatechange scrollchild
29
+
30
+ export type * from './types'
31
+
32
+ export const ScrollCoordinator = memo(forwardRef(ScrollCoordinatorImpl))
33
+
34
+ function ScrollCoordinatorImpl(
35
+ props: ScrollCoordinatorProps,
36
+ ref: ForwardedRef<ScrollCoordinatorRef>,
37
+ ) {
38
+ const {
39
+ id,
40
+ className,
41
+ style,
42
+ coordinatorProps,
43
+ headers,
44
+ toolbar,
45
+ slot,
46
+ refreshOptions = false,
47
+ bounces = false,
48
+ enableScroll = true,
49
+ refreshInSlot = false,
50
+ scrollBarEnable = false,
51
+ headerOverSlot = false,
52
+ granularity = 0.01,
53
+ popupOptions,
54
+ scrollWithNative = false,
55
+ onOffsetChange,
56
+ 'main-thread:onOffsetChange': onOffsetChangeMT,
57
+ 'main-thread:gesture': gesture,
58
+ onSticky,
59
+ onLeaveSticky,
60
+ } = props
61
+ const nativeRef = useRef<NodesRef>(null)
62
+ const headerRef = useRef<NodesRef>(null)
63
+ const refreshRef = useRef<NodesRef>(null)
64
+ const refreshHeaderSize = useRef(0)
65
+ const refreshOffset = useRef(0)
66
+ const stickyRef = useRef(false)
67
+ const [isSticky, setSticky] = useState(false)
68
+ const refreshProps = refreshOptions || undefined
69
+ const hasRefresh = refreshProps !== undefined
70
+ const enableRefresh = refreshProps?.enableRefresh ?? false
71
+
72
+ const scrollTo: ScrollCoordinatorRef['scrollTo'] = (
73
+ offset,
74
+ animated,
75
+ success,
76
+ fail,
77
+ ) => {
78
+ nativeRef.current?.invoke({
79
+ method: 'setFoldExpanded',
80
+ params: { offset, smooth: animated },
81
+ success,
82
+ fail,
83
+ }).exec()
84
+ }
85
+
86
+ useImperativeHandle(ref, () => ({
87
+ startRefresh() {
88
+ if (!enableRefresh) return
89
+ refreshRef.current?.invoke({ method: 'autoStartRefresh' }).exec()
90
+ },
91
+ finishRefresh() {
92
+ refreshRef.current?.invoke({ method: 'finishRefresh' }).exec()
93
+ },
94
+ scrollTo,
95
+ scrollToTop(animated, success, fail) {
96
+ scrollTo('0px', animated, success, fail)
97
+ },
98
+ scrollToSticky(animated, success, fail) {
99
+ // The native method clamps the requested offset to the header's range.
100
+ scrollTo('99999999px', animated, success, fail)
101
+ },
102
+ scrollIntoView(targetId, animated, success, fail) {
103
+ Promise.all([getRectById(targetId), getRectByRef(headerRef)])
104
+ .then(([target, header]) =>
105
+ scrollTo(`${target.top - header.top}px`, animated, success, fail)
106
+ )
107
+ .catch((error: unknown) => fail?.(error))
108
+ },
109
+ }))
110
+
111
+ const bindOffset = (event: ScrollCoordinatorOffsetEvent) => {
112
+ const { offset, height } = event.detail
113
+ onOffsetChange?.({ offset, height })
114
+ const sticky = height > 0 && offset / height >= 1 - granularity
115
+ if (sticky === stickyRef.current) return
116
+ // Native events can arrive before React commits the next render.
117
+ stickyRef.current = sticky
118
+ setSticky(sticky)
119
+ if (sticky) onSticky?.()
120
+ else onLeaveSticky?.()
121
+ }
122
+
123
+ const handleOffsetMT = (event: ScrollCoordinatorOffsetEvent) => {
124
+ 'main thread'
125
+ const { offset, height } = event.detail
126
+ onOffsetChangeMT?.({ offset, height })
127
+ }
128
+
129
+ const handleRefreshHeaderLayout = (event: LayoutChangeEvent) => {
130
+ refreshHeaderSize.current = event.detail.height
131
+ }
132
+
133
+ const handleRefreshOffset = (event: RefreshHeaderOffsetEvent) => {
134
+ const headerSize = refreshHeaderSize.current
135
+ const offset = event.detail.offsetPercent * headerSize
136
+ refreshOffset.current = offset
137
+ refreshProps?.onRefreshOffsetChange?.({
138
+ offset,
139
+ headerSize,
140
+ isDragging: event.detail.isDragging,
141
+ })
142
+ }
143
+
144
+ const handleStartRefresh = (event: RefreshStartRefreshEvent) => {
145
+ if (!enableRefresh) return
146
+ refreshProps?.onStartRefresh?.({
147
+ triggeredBy: event.detail.isManual ? 'drag' : 'startRefresh',
148
+ })
149
+ }
150
+
151
+ // The native release event is not yet declared in the public element types.
152
+ const refreshViewProps = {
153
+ bindheaderreleased: () => {
154
+ refreshProps?.onHeaderReleased?.({
155
+ offset: refreshOffset.current,
156
+ headerSize: refreshHeaderSize.current,
157
+ })
158
+ },
159
+ }
160
+
161
+ const coordinator = (
162
+ <scroll-coordinator
163
+ {...coordinatorProps}
164
+ ref={nativeRef}
165
+ id={id}
166
+ className={clsx('lynx-ui-scroll-coordinator__root', {
167
+ 'ui-sticky': isSticky,
168
+ }, !hasRefresh && className)}
169
+ style={hasRefresh ? undefined : style}
170
+ granularity={granularity}
171
+ {...(gesture ? { 'main-thread:gesture': gesture } : {})}
172
+ bounces={popupOptions?.enableHalfToFullScreen
173
+ ? false
174
+ : enableRefresh || bounces}
175
+ android-enable-touch-stop-fling={true}
176
+ enable-scroll={enableScroll}
177
+ enable-scroll-bar={scrollBarEnable}
178
+ header-over-slot={headerOverSlot}
179
+ refresh-mode={enableRefresh ? 'fold' : (refreshInSlot ? 'page' : 'none')}
180
+ bindoffset={bindOffset}
181
+ {...(onOffsetChangeMT
182
+ ? { 'main-thread:bindoffset': handleOffsetMT }
183
+ : {})}
184
+ name={popupOptions?.name}
185
+ compat-container-popup={Boolean(popupOptions?.enableHalfToFullScreen)}
186
+ android-nested-scroll-as-child={scrollWithNative}
187
+ >
188
+ {toolbar != null && (
189
+ <scroll-coordinator-toolbar className='lynx-ui-scroll-coordinator__toolbar'>
190
+ {toolbar}
191
+ </scroll-coordinator-toolbar>
192
+ )}
193
+ <scroll-coordinator-header
194
+ ref={headerRef}
195
+ id={id ? `${id}-header` : undefined}
196
+ className='lynx-ui-scroll-coordinator__header'
197
+ style={hasRefresh ? { minHeight: '1px' } : { height: 'max-content' }}
198
+ >
199
+ {headers}
200
+ </scroll-coordinator-header>
201
+ <scroll-coordinator-slot className='lynx-ui-scroll-coordinator__slot'>
202
+ {slot}
203
+ </scroll-coordinator-slot>
204
+ </scroll-coordinator>
205
+ )
206
+
207
+ if (!hasRefresh) return coordinator
208
+
209
+ return (
210
+ <refresh
211
+ {...refreshViewProps}
212
+ ref={refreshRef}
213
+ id={id ? `${id}-refresh` : undefined}
214
+ className={clsx('lynx-ui-scroll-coordinator__refresh', className, {
215
+ 'ui-sticky': isSticky,
216
+ })}
217
+ style={style}
218
+ enable-refresh={enableRefresh}
219
+ enable-loadmore={false}
220
+ detect-scrollchild={true}
221
+ bindstartrefresh={handleStartRefresh}
222
+ bindheaderoffset={handleRefreshOffset}
223
+ bindrefreshstatechange={(event: RefreshStateChangeEvent) => {
224
+ refreshProps?.onRefreshStateChange?.({ state: event.detail.state })
225
+ }}
226
+ >
227
+ <refresh-header
228
+ className='lynx-ui-scroll-coordinator__refresh-header'
229
+ bindlayoutchange={handleRefreshHeaderLayout}
230
+ >
231
+ {refreshProps.headerContent}
232
+ </refresh-header>
233
+ {coordinator}
234
+ </refresh>
235
+ )
236
+ }
package/src/styles.css ADDED
@@ -0,0 +1,43 @@
1
+ .lynx-ui-scroll-coordinator__refresh {
2
+ display: flex;
3
+ width: 100%;
4
+ height: 100%;
5
+ }
6
+
7
+ .lynx-ui-scroll-coordinator__refresh-header {
8
+ width: 100%;
9
+ position: absolute;
10
+ overflow: visible;
11
+ }
12
+
13
+ .lynx-ui-scroll-coordinator__root {
14
+ width: 100%;
15
+ height: 100%;
16
+ z-index: 0;
17
+ display: flex;
18
+ flex-direction: column;
19
+ overflow: visible;
20
+ }
21
+
22
+ .lynx-ui-scroll-coordinator__header {
23
+ position: absolute;
24
+ width: 100%;
25
+ z-index: 1;
26
+ overflow: visible;
27
+ }
28
+
29
+ .lynx-ui-scroll-coordinator__toolbar {
30
+ width: 100%;
31
+ display: flex;
32
+ z-index: 2;
33
+ overflow: visible;
34
+ }
35
+
36
+ .lynx-ui-scroll-coordinator__slot {
37
+ display: flex;
38
+ flex-direction: column;
39
+ width: 100%;
40
+ flex: 1;
41
+ z-index: 1;
42
+ overflow: visible;
43
+ }
@@ -0,0 +1,265 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ import type { ReactNode } from '@lynx-js/react'
6
+
7
+ import type { BaseGesture } from '@lynx-js/gesture-runtime'
8
+ import type { ComponentBasicProps } from '@lynx-js/lynx-ui-common'
9
+ import type {
10
+ ScrollCoordinatorProps as NativeScrollCoordinatorProps,
11
+ ScrollCoordinatorOffset,
12
+ } from '@lynx-js/types'
13
+
14
+ export type { ScrollCoordinatorOffset }
15
+
16
+ export interface ScrollCoordinatorRef {
17
+ /**
18
+ * Start the outer refresh through its native node. Requires enableRefresh.
19
+ * onStartRefresh reports triggeredBy: 'startRefresh'. Does not control slot refresh instances.
20
+ * @Android
21
+ * @iOS
22
+ */
23
+ startRefresh: () => void
24
+ /**
25
+ * End the outer refresh, including after a failed request. An existing refresh
26
+ * can still finish after enableRefresh becomes false. Does not reset list offsets.
27
+ * @Android
28
+ * @iOS
29
+ */
30
+ finishRefresh: () => void
31
+ /**
32
+ * Expand the header. Does not reset the nested list's own scroll position.
33
+ * @Android
34
+ * @iOS
35
+ */
36
+ scrollToTop: (
37
+ animated: boolean,
38
+ success?: (result: unknown) => void,
39
+ fail?: (result: unknown) => void,
40
+ ) => void
41
+ /**
42
+ * Collapse the header to its sticky position.
43
+ * @Android
44
+ * @iOS
45
+ */
46
+ scrollToSticky: (
47
+ animated: boolean,
48
+ success?: (result: unknown) => void,
49
+ fail?: (result: unknown) => void,
50
+ ) => void
51
+ /**
52
+ * Set the header offset. The native coordinator clamps it to the scrollable range.
53
+ * @Android
54
+ * @iOS
55
+ */
56
+ scrollTo: (
57
+ offset: `${number}px` | `${number}rpx`,
58
+ animated: boolean,
59
+ success?: (result: unknown) => void,
60
+ fail?: (result: unknown) => void,
61
+ ) => void
62
+ /**
63
+ * Scroll to an element inside headers, measured relative to this instance's header.
64
+ * @Android
65
+ * @iOS
66
+ */
67
+ scrollIntoView: (
68
+ id: string,
69
+ animated: boolean,
70
+ success?: (result: unknown) => void,
71
+ fail?: (result: unknown) => void,
72
+ ) => void
73
+ }
74
+
75
+ export interface ScrollCoordinatorUIVariants {
76
+ /**
77
+ * Applied to the coordinator and outer refresh wrapper while the header is collapsed.
78
+ * @zh 头部折叠时,应用于协调器和外层刷新容器。
79
+ */
80
+ 'ui-sticky'?: boolean
81
+ }
82
+
83
+ /** Native refresh options with the same callback shapes as FeedList. */
84
+ export interface ScrollCoordinatorRefreshOptions {
85
+ /**
86
+ * Allow pull gestures and startRefresh() to start the outer refresh.
87
+ * Toggle this flag to preserve the mounted content and its scroll position.
88
+ * @Android
89
+ * @iOS
90
+ */
91
+ enableRefresh: boolean
92
+ /**
93
+ * Refresh header content. Give it a nonzero height to define the pull threshold.
94
+ * Keep its dimensions stable while refreshing to avoid resetting the native header position.
95
+ * @Android
96
+ * @iOS
97
+ */
98
+ headerContent: ReactNode
99
+ /**
100
+ * Start loading data. Always call ref.finishRefresh() when the request settles.
101
+ * Returning a Promise does not automatically end the refresh.
102
+ * @Android
103
+ * @iOS
104
+ */
105
+ onStartRefresh?: (event: { triggeredBy: 'startRefresh' | 'drag' }) => void
106
+ /**
107
+ * Pull offset and measured header height in px. The height is zero until layout.
108
+ * Progress is offset / headerSize when headerSize > 0, and may exceed 1.
109
+ * @Android
110
+ * @iOS
111
+ */
112
+ onRefreshOffsetChange?: (
113
+ event: { offset: number, headerSize: number, isDragging: boolean },
114
+ ) => void
115
+ /**
116
+ * Native state: 0 idle, 1 released past the threshold, 2 refreshing.
117
+ * Event order is platform-dependent. Use isDragging from the offset event for drag state.
118
+ * @Android
119
+ * @iOS
120
+ */
121
+ onRefreshStateChange?: (event: { state: number }) => void
122
+ /**
123
+ * The native header was released. Reports the latest offset and measured height in px.
124
+ * @Android
125
+ * @iOS
126
+ */
127
+ onHeaderReleased?: (event: { offset: number, headerSize: number }) => void
128
+ }
129
+
130
+ /** Coordinates a collapsible header with nested vertical lists or scroll views. */
131
+ export interface ScrollCoordinatorProps extends ComponentBasicProps {
132
+ /**
133
+ * Optional native coordinator ID. Imperative methods use instance-local node refs.
134
+ * @Android
135
+ * @iOS
136
+ */
137
+ id?: string
138
+ /**
139
+ * Collapsible header content.
140
+ * @Android
141
+ * @iOS
142
+ */
143
+ headers?: ReactNode
144
+ /**
145
+ * Persistent toolbar. Its height is subtracted from the header's collapse range.
146
+ * @Android
147
+ * @iOS
148
+ */
149
+ toolbar?: ReactNode
150
+ /**
151
+ * Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
152
+ * @Android
153
+ * @iOS
154
+ */
155
+ slot?: ReactNode
156
+ /**
157
+ * Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot.
158
+ * Providing an options object mounts the refresh wrapper, even while enableRefresh is false.
159
+ * className and style apply to this wrapper; otherwise they apply to the native coordinator.
160
+ * No implementation mode is required. @defaultValue false
161
+ * @Android
162
+ * @iOS
163
+ */
164
+ refreshOptions?: false | ScrollCoordinatorRefreshOptions
165
+ /**
166
+ * Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it. @defaultValue false
167
+ * @iOS
168
+ */
169
+ bounces?: boolean
170
+ /**
171
+ * Enable vertical coordinator scrolling. @defaultValue true
172
+ * @Android
173
+ * @iOS
174
+ */
175
+ enableScroll?: boolean
176
+ /**
177
+ * Place the overflowing header above the slot. @defaultValue false
178
+ * @Android
179
+ * @iOS
180
+ */
181
+ headerOverSlot?: boolean
182
+ /**
183
+ * Use independent refresh elements inside the slot. Each nested refresh must
184
+ * finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
185
+ * @defaultValue false
186
+ * @Android
187
+ * @iOS
188
+ */
189
+ refreshInSlot?: boolean
190
+ /**
191
+ * Show the coordinator scrollbar on supported platforms. @defaultValue false
192
+ * @Android
193
+ * @iOS
194
+ */
195
+ scrollBarEnable?: boolean
196
+ /**
197
+ * Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold. @defaultValue 0.01
198
+ * @Android
199
+ * @iOS
200
+ */
201
+ granularity?: number
202
+ /**
203
+ * Native host popup integration for hosts that support half-to-full-screen expansion.
204
+ * @Android
205
+ * @iOS
206
+ */
207
+ popupOptions?: {
208
+ /**
209
+ * Name identifying the coordinator to the native popup container.
210
+ * @Android
211
+ * @iOS
212
+ */
213
+ name: string
214
+ /**
215
+ * Enable native popup coordination and disable bounce.
216
+ * @Android
217
+ * @iOS
218
+ */
219
+ enableHalfToFullScreen: boolean
220
+ }
221
+ /**
222
+ * Participate as a nested scrolling child of a native Android container. @defaultValue false
223
+ * @Android
224
+ */
225
+ scrollWithNative?: boolean
226
+ /**
227
+ * Native gesture attached to the coordinator.
228
+ * @Android
229
+ * @iOS
230
+ */
231
+ 'main-thread:gesture'?: BaseGesture
232
+ /**
233
+ * Native properties passed explicitly to the coordinator. Managed properties take precedence.
234
+ * @Android
235
+ * @iOS
236
+ */
237
+ coordinatorProps?: Omit<
238
+ NativeScrollCoordinatorProps,
239
+ 'ref' | 'children' | 'id' | 'style' | 'className'
240
+ >
241
+ /**
242
+ * Header offset and total collapse range, in px.
243
+ * @Android
244
+ * @iOS
245
+ */
246
+ onOffsetChange?: (event: ScrollCoordinatorOffset) => void
247
+ /**
248
+ * Header offset callback on the main thread. Pass a function with the 'main thread' directive.
249
+ * @Android
250
+ * @iOS
251
+ */
252
+ 'main-thread:onOffsetChange'?: (event: ScrollCoordinatorOffset) => void
253
+ /**
254
+ * Called once when the header reaches the sticky threshold.
255
+ * @Android
256
+ * @iOS
257
+ */
258
+ onSticky?: () => void
259
+ /**
260
+ * Called once when the header leaves the sticky threshold.
261
+ * @Android
262
+ * @iOS
263
+ */
264
+ onLeaveSticky?: () => void
265
+ }
@@ -0,0 +1,5 @@
1
+ // Copyright 2026 The Lynx Authors. All rights reserved.
2
+ // Licensed under the Apache License Version 2.0 that can be found in the
3
+ // LICENSE file in the root directory of this source tree.
4
+
5
+ export type * from './index.docs'
@@ -0,0 +1,7 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.docs.json",
3
+ "include": [
4
+ "src",
5
+ "dist/types/index.docs.d.ts"
6
+ ]
7
+ }
package/tsconfig.json ADDED
@@ -0,0 +1,14 @@
1
+ {
2
+ "extends": "../../tools/configs/tsconfig.lib.json",
3
+ "compilerOptions": {
4
+ "rootDir": "./src",
5
+ },
6
+ "include": [
7
+ "src",
8
+ ],
9
+ "exclude": [
10
+ "**/*.test.ts",
11
+ "**/*.test.tsx",
12
+ "**/__tests__/**",
13
+ ],
14
+ }