@lynx-js/lynx-ui-scroll-coordinator 0.0.0-oidc-bootstrap.0 → 3.139.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,238 @@
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
+ /** Applied to the coordinator and outer refresh wrapper while the header is collapsed. */
48
+ 'ui-sticky'?: boolean;
49
+ }
50
+ /** Native refresh options with the same callback shapes as FeedList. */
51
+ export interface ScrollCoordinatorRefreshOptions {
52
+ /**
53
+ * Allow pull gestures and startRefresh() to start the outer refresh.
54
+ * Toggle this flag to preserve the mounted content and its scroll position.
55
+ * @Android
56
+ * @iOS
57
+ */
58
+ enableRefresh: boolean;
59
+ /**
60
+ * Refresh header content. Give it a nonzero height to define the pull threshold.
61
+ * Keep its dimensions stable while refreshing to avoid resetting the native header position.
62
+ * @Android
63
+ * @iOS
64
+ */
65
+ headerContent: ReactNode;
66
+ /**
67
+ * Start loading data. Always call ref.finishRefresh() when the request settles.
68
+ * Returning a Promise does not automatically end the refresh.
69
+ * @Android
70
+ * @iOS
71
+ */
72
+ onStartRefresh?: (event: {
73
+ triggeredBy: 'startRefresh' | 'drag';
74
+ }) => void;
75
+ /**
76
+ * Pull offset and measured header height in px. The height is zero until layout.
77
+ * Progress is offset / headerSize when headerSize > 0, and may exceed 1.
78
+ * @Android
79
+ * @iOS
80
+ */
81
+ onRefreshOffsetChange?: (event: {
82
+ offset: number;
83
+ headerSize: number;
84
+ isDragging: boolean;
85
+ }) => void;
86
+ /**
87
+ * Native state: 0 idle, 1 released past the threshold, 2 refreshing.
88
+ * Event order is platform-dependent. Use isDragging from the offset event for drag state.
89
+ * @Android
90
+ * @iOS
91
+ */
92
+ onRefreshStateChange?: (event: {
93
+ state: number;
94
+ }) => void;
95
+ /**
96
+ * The native header was released. Reports the latest offset and measured height in px.
97
+ * @Android
98
+ * @iOS
99
+ */
100
+ onHeaderReleased?: (event: {
101
+ offset: number;
102
+ headerSize: number;
103
+ }) => void;
104
+ }
105
+ /** Coordinates a collapsible header with nested vertical lists or scroll views. */
106
+ export interface ScrollCoordinatorProps extends ComponentBasicProps {
107
+ /**
108
+ * Optional native coordinator ID. Imperative methods use instance-local node refs.
109
+ * @Android
110
+ * @iOS
111
+ */
112
+ id?: string;
113
+ /**
114
+ * Collapsible header content.
115
+ * @Android
116
+ * @iOS
117
+ */
118
+ headers?: ReactNode;
119
+ /**
120
+ * Persistent toolbar. Its height is subtracted from the header's collapse range.
121
+ * @Android
122
+ * @iOS
123
+ */
124
+ toolbar?: ReactNode;
125
+ /**
126
+ * Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
127
+ * @Android
128
+ * @iOS
129
+ */
130
+ slot?: ReactNode;
131
+ /**
132
+ * Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot.
133
+ * Providing an options object mounts the refresh wrapper, even while enableRefresh is false.
134
+ * className and style apply to this wrapper; otherwise they apply to the native coordinator.
135
+ * No implementation mode is required. @defaultValue false
136
+ * @Android
137
+ * @iOS
138
+ */
139
+ refreshOptions?: false | ScrollCoordinatorRefreshOptions;
140
+ /**
141
+ * Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it. @defaultValue false
142
+ * @iOS
143
+ */
144
+ bounces?: boolean;
145
+ /**
146
+ * Enable vertical coordinator scrolling. @defaultValue true
147
+ * @Android
148
+ * @iOS
149
+ */
150
+ enableScroll?: boolean;
151
+ /**
152
+ * Place the overflowing header above the slot. @defaultValue false
153
+ * @Android
154
+ * @iOS
155
+ */
156
+ headerOverSlot?: boolean;
157
+ /**
158
+ * Use independent refresh elements inside the slot. Each nested refresh must
159
+ * finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
160
+ * @defaultValue false
161
+ * @Android
162
+ * @iOS
163
+ */
164
+ refreshInSlot?: boolean;
165
+ /**
166
+ * Show the coordinator scrollbar on supported platforms. @defaultValue false
167
+ * @Android
168
+ * @iOS
169
+ */
170
+ scrollBarEnable?: boolean;
171
+ /**
172
+ * Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold. @defaultValue 0.01
173
+ * @Android
174
+ * @iOS
175
+ */
176
+ granularity?: number;
177
+ /**
178
+ * Native host popup integration for hosts that support half-to-full-screen expansion.
179
+ * @Android
180
+ * @iOS
181
+ */
182
+ popupOptions?: {
183
+ /**
184
+ * Name identifying the coordinator to the native popup container.
185
+ * @Android
186
+ * @iOS
187
+ */
188
+ name: string;
189
+ /**
190
+ * Enable native popup coordination and disable bounce.
191
+ * @Android
192
+ * @iOS
193
+ */
194
+ enableHalfToFullScreen: boolean;
195
+ };
196
+ /**
197
+ * Participate as a nested scrolling child of a native Android container. @defaultValue false
198
+ * @Android
199
+ */
200
+ scrollWithNative?: boolean;
201
+ /**
202
+ * Native gesture attached to the coordinator.
203
+ * @Android
204
+ * @iOS
205
+ */
206
+ 'main-thread:gesture'?: BaseGesture;
207
+ /**
208
+ * Native properties passed explicitly to the coordinator. Managed properties take precedence.
209
+ * @Android
210
+ * @iOS
211
+ */
212
+ coordinatorProps?: Omit<NativeScrollCoordinatorProps, 'ref' | 'children' | 'id' | 'style' | 'className'>;
213
+ /**
214
+ * Header offset and total collapse range, in px.
215
+ * @Android
216
+ * @iOS
217
+ */
218
+ onOffsetChange?: (event: ScrollCoordinatorOffset) => void;
219
+ /**
220
+ * Header offset callback on the main thread. Pass a function with the 'main thread' directive.
221
+ * @Android
222
+ * @iOS
223
+ */
224
+ 'main-thread:onOffsetChange'?: (event: ScrollCoordinatorOffset) => void;
225
+ /**
226
+ * Called once when the header reaches the sticky threshold.
227
+ * @Android
228
+ * @iOS
229
+ */
230
+ onSticky?: () => void;
231
+ /**
232
+ * Called once when the header leaves the sticky threshold.
233
+ * @Android
234
+ * @iOS
235
+ */
236
+ onLeaveSticky?: () => void;
237
+ }
238
+ //# 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.139.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.139.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,262 @@
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
+ /** Applied to the coordinator and outer refresh wrapper while the header is collapsed. */
77
+ 'ui-sticky'?: boolean
78
+ }
79
+
80
+ /** Native refresh options with the same callback shapes as FeedList. */
81
+ export interface ScrollCoordinatorRefreshOptions {
82
+ /**
83
+ * Allow pull gestures and startRefresh() to start the outer refresh.
84
+ * Toggle this flag to preserve the mounted content and its scroll position.
85
+ * @Android
86
+ * @iOS
87
+ */
88
+ enableRefresh: boolean
89
+ /**
90
+ * Refresh header content. Give it a nonzero height to define the pull threshold.
91
+ * Keep its dimensions stable while refreshing to avoid resetting the native header position.
92
+ * @Android
93
+ * @iOS
94
+ */
95
+ headerContent: ReactNode
96
+ /**
97
+ * Start loading data. Always call ref.finishRefresh() when the request settles.
98
+ * Returning a Promise does not automatically end the refresh.
99
+ * @Android
100
+ * @iOS
101
+ */
102
+ onStartRefresh?: (event: { triggeredBy: 'startRefresh' | 'drag' }) => void
103
+ /**
104
+ * Pull offset and measured header height in px. The height is zero until layout.
105
+ * Progress is offset / headerSize when headerSize > 0, and may exceed 1.
106
+ * @Android
107
+ * @iOS
108
+ */
109
+ onRefreshOffsetChange?: (
110
+ event: { offset: number, headerSize: number, isDragging: boolean },
111
+ ) => void
112
+ /**
113
+ * Native state: 0 idle, 1 released past the threshold, 2 refreshing.
114
+ * Event order is platform-dependent. Use isDragging from the offset event for drag state.
115
+ * @Android
116
+ * @iOS
117
+ */
118
+ onRefreshStateChange?: (event: { state: number }) => void
119
+ /**
120
+ * The native header was released. Reports the latest offset and measured height in px.
121
+ * @Android
122
+ * @iOS
123
+ */
124
+ onHeaderReleased?: (event: { offset: number, headerSize: number }) => void
125
+ }
126
+
127
+ /** Coordinates a collapsible header with nested vertical lists or scroll views. */
128
+ export interface ScrollCoordinatorProps extends ComponentBasicProps {
129
+ /**
130
+ * Optional native coordinator ID. Imperative methods use instance-local node refs.
131
+ * @Android
132
+ * @iOS
133
+ */
134
+ id?: string
135
+ /**
136
+ * Collapsible header content.
137
+ * @Android
138
+ * @iOS
139
+ */
140
+ headers?: ReactNode
141
+ /**
142
+ * Persistent toolbar. Its height is subtracted from the header's collapse range.
143
+ * @Android
144
+ * @iOS
145
+ */
146
+ toolbar?: ReactNode
147
+ /**
148
+ * Content below the header, typically a vertical List, ScrollView, or ViewPager of lists.
149
+ * @Android
150
+ * @iOS
151
+ */
152
+ slot?: ReactNode
153
+ /**
154
+ * Configure outer native refresh. Enabled outer refresh takes precedence over refreshInSlot.
155
+ * Providing an options object mounts the refresh wrapper, even while enableRefresh is false.
156
+ * className and style apply to this wrapper; otherwise they apply to the native coordinator.
157
+ * No implementation mode is required. @defaultValue false
158
+ * @Android
159
+ * @iOS
160
+ */
161
+ refreshOptions?: false | ScrollCoordinatorRefreshOptions
162
+ /**
163
+ * Enable bounce on supported platforms. Outer refresh always enables it unless popupOptions disables it. @defaultValue false
164
+ * @iOS
165
+ */
166
+ bounces?: boolean
167
+ /**
168
+ * Enable vertical coordinator scrolling. @defaultValue true
169
+ * @Android
170
+ * @iOS
171
+ */
172
+ enableScroll?: boolean
173
+ /**
174
+ * Place the overflowing header above the slot. @defaultValue false
175
+ * @Android
176
+ * @iOS
177
+ */
178
+ headerOverSlot?: boolean
179
+ /**
180
+ * Use independent refresh elements inside the slot. Each nested refresh must
181
+ * finish its own refresh through its ref; finishRefresh only affects the outer wrapper.
182
+ * @defaultValue false
183
+ * @Android
184
+ * @iOS
185
+ */
186
+ refreshInSlot?: boolean
187
+ /**
188
+ * Show the coordinator scrollbar on supported platforms. @defaultValue false
189
+ * @Android
190
+ * @iOS
191
+ */
192
+ scrollBarEnable?: boolean
193
+ /**
194
+ * Offset event granularity as a fraction of the collapse range. Also sets the sticky threshold. @defaultValue 0.01
195
+ * @Android
196
+ * @iOS
197
+ */
198
+ granularity?: number
199
+ /**
200
+ * Native host popup integration for hosts that support half-to-full-screen expansion.
201
+ * @Android
202
+ * @iOS
203
+ */
204
+ popupOptions?: {
205
+ /**
206
+ * Name identifying the coordinator to the native popup container.
207
+ * @Android
208
+ * @iOS
209
+ */
210
+ name: string
211
+ /**
212
+ * Enable native popup coordination and disable bounce.
213
+ * @Android
214
+ * @iOS
215
+ */
216
+ enableHalfToFullScreen: boolean
217
+ }
218
+ /**
219
+ * Participate as a nested scrolling child of a native Android container. @defaultValue false
220
+ * @Android
221
+ */
222
+ scrollWithNative?: boolean
223
+ /**
224
+ * Native gesture attached to the coordinator.
225
+ * @Android
226
+ * @iOS
227
+ */
228
+ 'main-thread:gesture'?: BaseGesture
229
+ /**
230
+ * Native properties passed explicitly to the coordinator. Managed properties take precedence.
231
+ * @Android
232
+ * @iOS
233
+ */
234
+ coordinatorProps?: Omit<
235
+ NativeScrollCoordinatorProps,
236
+ 'ref' | 'children' | 'id' | 'style' | 'className'
237
+ >
238
+ /**
239
+ * Header offset and total collapse range, in px.
240
+ * @Android
241
+ * @iOS
242
+ */
243
+ onOffsetChange?: (event: ScrollCoordinatorOffset) => void
244
+ /**
245
+ * Header offset callback on the main thread. Pass a function with the 'main thread' directive.
246
+ * @Android
247
+ * @iOS
248
+ */
249
+ 'main-thread:onOffsetChange'?: (event: ScrollCoordinatorOffset) => void
250
+ /**
251
+ * Called once when the header reaches the sticky threshold.
252
+ * @Android
253
+ * @iOS
254
+ */
255
+ onSticky?: () => void
256
+ /**
257
+ * Called once when the header leaves the sticky threshold.
258
+ * @Android
259
+ * @iOS
260
+ */
261
+ onLeaveSticky?: () => void
262
+ }
@@ -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
+ }