@lynx-js/lynx-ui-view-pager 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
@@ -1,4 +1,4 @@
1
- Apache License
1
+ Apache License
2
2
  Version 2.0, January 2004
3
3
  http://www.apache.org/licenses/
4
4
 
package/README.md CHANGED
@@ -1,9 +1,34 @@
1
1
  # @lynx-js/lynx-ui-view-pager
2
2
 
3
- > Placeholder package published only to enable npm Trusted Publishing (OIDC) setup.
3
+ A page-snapped horizontal content navigator for ReactLynx with optional off-screen lazy rendering.
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-view-pager`.
12
+
13
+ ## Usage
14
+
15
+ ```tsx
16
+ import { ViewPager } from '@lynx-js/lynx-ui'
17
+
18
+ <ViewPager
19
+ data={[{ id: 'first', title: 'First' }, { id: 'second', title: 'Second' }]}
20
+ getItemKey={page => page.id}
21
+ itemStyle={{ width: '100%', height: '100%' }}
22
+ style={{ width: '100%', height: '400px' }}
23
+ >
24
+ {page => <text>{page.title}</text>}
25
+ </ViewPager>
26
+ ```
27
+
28
+ [View the examples](https://github.com/lynx-family/lynx-ui/tree/main/apps/examples/ViewPager)
29
+
30
+ Use `getItemProps` when individual native page items need their own style or accessibility attributes. Its styles override matching `itemStyle` properties.
31
+
32
+ ## License
33
+
34
+ [lynx-ui](https://github.com/lynx-family/lynx-ui) is licensed under the [Apache License 2.0](./LICENSE).
@@ -0,0 +1,8 @@
1
+ import type { ForwardedRef, ReactElement } from '@lynx-js/react';
2
+ import type { ViewPagerProps, ViewPagerRef } from './types/index.js';
3
+ export type * from './types/index.js';
4
+ type ViewPagerComponent = <T>(props: ViewPagerProps<T> & {
5
+ ref?: ForwardedRef<ViewPagerRef>;
6
+ }) => ReactElement;
7
+ export declare const ViewPager: ViewPagerComponent;
8
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAa,MAAM,gBAAgB,CAAA;AAM3E,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAG3D,mBAAmB,SAAS,CAAA;AAE5B,KAAK,kBAAkB,GAAG,CAAC,CAAC,EAC1B,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,YAAY,CAAC,YAAY,CAAC,CAAA;CAAE,KAC5D,YAAY,CAAA;AAYjB,eAAO,MAAM,SAAS,EAAsC,kBAAkB,CAAA"}
package/dist/index.jsx ADDED
@@ -0,0 +1,82 @@
1
+ import { forwardRef, memo, useImperativeHandle, useRef } from "@lynx-js/react";
2
+ import { LazyComponent } from "@lynx-js/lynx-ui-lazy-component";
3
+ import { clsx } from "clsx";
4
+ import { normalizeIndex } from "./utils.jsx";
5
+ function DeferredPageContent(props) {
6
+ return props.renderItem(props.item, props.index);
7
+ }
8
+ const ViewPager = memo(forwardRef(ViewPagerImpl));
9
+ function ViewPagerImpl(props, ref) {
10
+ const { data, getItemKey, children, initialSelectIndex = 0, id, className, style, itemClassName, itemStyle, getItemProps, viewpagerProps, enableScroll = true, bounces = true, lazyOptions, onPageChange, onPageWillChange, onOffsetChange, 'main-thread:onPageChange': onPageChangeMT, 'main-thread:onPageWillChange': onPageWillChangeMT, 'main-thread:onOffsetChange': onOffsetChangeMT } = props;
11
+ const initialIndex = useRef(initialSelectIndex);
12
+ const nativeRef = useRef(null);
13
+ const countRef = useRef(data.length);
14
+ countRef.current = data.length;
15
+ const normalizedInitialIndex = normalizeIndex(initialIndex.current, data.length);
16
+ const initialItemKey = useRef(void 0);
17
+ if (void 0 === initialItemKey.current && data.length > 0) initialItemKey.current = getItemKey?.(data[normalizedInitialIndex], normalizedInitialIndex) ?? normalizedInitialIndex;
18
+ useImperativeHandle(ref, ()=>({
19
+ scrollToPage (next, smooth, success, fail) {
20
+ if (0 === countRef.current) return;
21
+ nativeRef.current?.invoke({
22
+ method: 'selectTab',
23
+ params: {
24
+ index: normalizeIndex(next, countRef.current),
25
+ smooth: smooth ?? true
26
+ },
27
+ success,
28
+ fail
29
+ }).exec();
30
+ }
31
+ }));
32
+ const renderItem = children;
33
+ const keepItemView = lazyOptions?.enableLazy === true;
34
+ const eventProps = {
35
+ ...onPageChange && {
36
+ bindchange: onPageChange
37
+ },
38
+ ...onPageWillChange && {
39
+ bindwillchange: onPageWillChange
40
+ },
41
+ ...onOffsetChange && {
42
+ bindoffsetchange: onOffsetChange
43
+ },
44
+ ...onPageChangeMT && {
45
+ 'main-thread:bindchange': onPageChangeMT
46
+ },
47
+ ...onPageWillChangeMT && {
48
+ 'main-thread:bindwillchange': onPageWillChangeMT
49
+ },
50
+ ...onOffsetChangeMT && {
51
+ 'main-thread:bindoffsetchange': onOffsetChangeMT
52
+ }
53
+ };
54
+ return <viewpager {...viewpagerProps} ref={nativeRef} id={id} className={className} style={{
55
+ width: '100%',
56
+ display: 'flex',
57
+ flexDirection: 'row',
58
+ ...style
59
+ }} initial-select-index={normalizedInitialIndex} align-width={true} enable-scroll={enableScroll} allow-horizontal-gesture={enableScroll} bounces={bounces} keep-item-view={keepItemView} {...eventProps}>
60
+ {data.map((item, index)=>{
61
+ const itemKey = getItemKey?.(item, index) ?? index;
62
+ const perItemProps = getItemProps?.(item, index);
63
+ return <viewpager-item {...perItemProps} key={itemKey} className={clsx(itemClassName, perItemProps?.className)} style={{
64
+ display: 'flex',
65
+ width: '100%',
66
+ flexShrink: 0,
67
+ ...itemStyle,
68
+ ...perItemProps?.style
69
+ }}>
70
+ {lazyOptions?.enableLazy && itemKey !== initialItemKey.current ? <LazyComponent pid={`lynx-ui-view-pager-${String(itemKey)}`} scene={lazyOptions.scene} estimatedStyle={{
71
+ width: '100%',
72
+ height: '100%'
73
+ }} left={lazyOptions.exposureLeft} right={lazyOptions.exposureRight}>
74
+ <DeferredPageContent item={item} index={index} renderItem={renderItem}/>
75
+ </LazyComponent> : renderItem(item, index)}
76
+ </viewpager-item>;
77
+ })}
78
+ </viewpager>;
79
+ }
80
+ export { ViewPager };
81
+
82
+ //# 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 { forwardRef, memo, useImperativeHandle, useRef } from '@lynx-js/react'\nimport type { ForwardedRef, ReactElement, ReactNode } from '@lynx-js/react'\n\nimport { LazyComponent } from '@lynx-js/lynx-ui-lazy-component'\nimport type { NodesRef } from '@lynx-js/types'\nimport { clsx } from 'clsx'\n\nimport type { ViewPagerProps, ViewPagerRef } from './types'\nimport { normalizeIndex } from './utils'\n\nexport type * from './types'\n\ntype ViewPagerComponent = <T>(\n props: ViewPagerProps<T> & { ref?: ForwardedRef<ViewPagerRef> },\n) => ReactElement\n\ninterface DeferredPageContentProps {\n item: unknown\n index: number\n renderItem: (item: unknown, index: number) => ReactNode\n}\n\nfunction DeferredPageContent(props: DeferredPageContentProps) {\n return props.renderItem(props.item, props.index)\n}\n\nexport const ViewPager = memo(forwardRef(ViewPagerImpl)) as ViewPagerComponent\n\nfunction ViewPagerImpl<T>(\n props: ViewPagerProps<T>,\n ref: ForwardedRef<ViewPagerRef>,\n) {\n const {\n data,\n getItemKey,\n children,\n initialSelectIndex = 0,\n id,\n className,\n style,\n itemClassName,\n itemStyle,\n getItemProps,\n viewpagerProps,\n enableScroll = true,\n bounces = true,\n lazyOptions,\n onPageChange,\n onPageWillChange,\n onOffsetChange,\n 'main-thread:onPageChange': onPageChangeMT,\n 'main-thread:onPageWillChange': onPageWillChangeMT,\n 'main-thread:onOffsetChange': onOffsetChangeMT,\n } = props\n const initialIndex = useRef(initialSelectIndex)\n const nativeRef = useRef<NodesRef>(null)\n const countRef = useRef(data.length)\n countRef.current = data.length\n const normalizedInitialIndex = normalizeIndex(\n initialIndex.current,\n data.length,\n )\n const initialItemKey = useRef<string | number | undefined>(undefined)\n if (initialItemKey.current === undefined && data.length > 0) {\n initialItemKey.current = getItemKey?.(\n data[normalizedInitialIndex],\n normalizedInitialIndex,\n ) ?? normalizedInitialIndex\n }\n\n useImperativeHandle(ref, () => ({\n scrollToPage(next, smooth, success, fail) {\n if (countRef.current === 0) return\n nativeRef.current?.invoke({\n method: 'selectTab',\n params: {\n index: normalizeIndex(next, countRef.current),\n smooth: smooth ?? true,\n },\n success,\n fail,\n }).exec()\n },\n }))\n\n const renderItem = children as (item: unknown, index: number) => ReactNode\n const keepItemView = lazyOptions?.enableLazy === true\n // Lynx can invoke an undefined native event binding during a swipe.\n const eventProps = {\n ...(onPageChange && { bindchange: onPageChange }),\n ...(onPageWillChange && { bindwillchange: onPageWillChange }),\n ...(onOffsetChange && { bindoffsetchange: onOffsetChange }),\n ...(onPageChangeMT && { 'main-thread:bindchange': onPageChangeMT }),\n ...(onPageWillChangeMT && {\n 'main-thread:bindwillchange': onPageWillChangeMT,\n }),\n ...(onOffsetChangeMT && {\n 'main-thread:bindoffsetchange': onOffsetChangeMT,\n }),\n }\n\n return (\n <viewpager\n {...viewpagerProps}\n ref={nativeRef}\n id={id}\n className={className}\n style={{ width: '100%', display: 'flex', flexDirection: 'row', ...style }}\n initial-select-index={normalizedInitialIndex}\n align-width={true}\n enable-scroll={enableScroll}\n allow-horizontal-gesture={enableScroll}\n bounces={bounces}\n keep-item-view={keepItemView}\n {...eventProps}\n >\n {data.map((item, index) => {\n const itemKey = getItemKey?.(item, index) ?? index\n const perItemProps = getItemProps?.(item, index)\n return (\n <viewpager-item\n {...perItemProps}\n key={itemKey}\n className={clsx(itemClassName, perItemProps?.className)}\n style={{\n display: 'flex',\n width: '100%',\n flexShrink: 0,\n ...itemStyle,\n ...perItemProps?.style,\n }}\n >\n {lazyOptions?.enableLazy && itemKey !== initialItemKey.current\n ? (\n <LazyComponent\n pid={`lynx-ui-view-pager-${String(itemKey)}`}\n scene={lazyOptions.scene}\n estimatedStyle={{ width: '100%', height: '100%' }}\n left={lazyOptions.exposureLeft}\n right={lazyOptions.exposureRight}\n >\n <DeferredPageContent\n item={item}\n index={index}\n renderItem={renderItem}\n />\n </LazyComponent>\n )\n : renderItem(item, index)}\n </viewpager-item>\n )\n })}\n </viewpager>\n )\n}\n"],"names":["DeferredPageContent","props","ViewPager","memo","forwardRef","ViewPagerImpl","ref","data","getItemKey","children","initialSelectIndex","id","className","style","itemClassName","itemStyle","getItemProps","viewpagerProps","enableScroll","bounces","lazyOptions","onPageChange","onPageWillChange","onOffsetChange","onPageChangeMT","onPageWillChangeMT","onOffsetChangeMT","initialIndex","useRef","nativeRef","countRef","normalizedInitialIndex","normalizeIndex","initialItemKey","undefined","useImperativeHandle","next","smooth","success","fail","renderItem","keepItemView","eventProps","viewpager","item","index","itemKey","perItemProps","viewpager-item","clsx","LazyComponent","String"],"mappings":"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"}
@@ -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,174 @@
1
+ import type { ReactNode } from '@lynx-js/react';
2
+ import type { ComponentBasicProps } from '@lynx-js/lynx-ui-common';
3
+ import type { ViewPagerItemProps as NativeViewPagerItemProps, ViewPagerProps as NativeViewPagerProps, ViewPagerChangeEvent, ViewPagerOffsetChangeEvent, ViewPagerWillChangeEvent } from '@lynx-js/types';
4
+ export type { ViewPagerChangeEvent, ViewPagerOffsetChangeEvent, ViewPagerWillChangeEvent, };
5
+ export interface ViewPagerRef {
6
+ /**
7
+ * Slide to a page through the native node ref. Animation defaults to true.
8
+ * Indexes are clamped to available pages. Empty pagers ignore requests.
9
+ * Completion is reported through onPageChange; success confirms invocation.
10
+ * @zh 通过原生节点引用切换页面,默认使用动画。索引限制在有效范围内,空列表忽略请求。onPageChange 表示切换完成,success 表示调用成功。
11
+ * @Android
12
+ * @iOS
13
+ */
14
+ scrollToPage: (index: number, smooth?: boolean, success?: (result: unknown) => void, fail?: (result: unknown) => void) => void;
15
+ }
16
+ export type ViewPagerExposureMargin = `${number}px` | `${number}rpx`;
17
+ export type ViewPagerItemProps = Omit<NativeViewPagerItemProps, 'key' | 'ref' | 'children' | 'style'> & {
18
+ style?: ComponentBasicProps['style'];
19
+ };
20
+ export type ViewPagerLazyOptions = {
21
+ /** Disable lazy rendering. @zh 禁用懒渲染。 */
22
+ enableLazy: false;
23
+ } | {
24
+ /** Enable exposure-driven lazy rendering for pages other than the initial page. @zh 为初始页面以外的页面启用基于曝光的懒渲染。 */
25
+ enableLazy: true;
26
+ /** Exposure scene shared by this pager's lazy placeholders. It must be unique on the page. @zh 此分页器的懒加载占位节点共用的曝光场景,在页面内必须唯一。 */
27
+ scene: string;
28
+ /** Extend or shrink the placeholder's left exposure boundary. @defaultValue 10px @zh 扩展或缩小占位节点的左侧曝光边界。 */
29
+ exposureLeft?: ViewPagerExposureMargin;
30
+ /** Extend or shrink the placeholder's right exposure boundary. @defaultValue 10px @zh 扩展或缩小占位节点的右侧曝光边界。 */
31
+ exposureRight?: ViewPagerExposureMargin;
32
+ };
33
+ export interface ViewPagerProps<T> extends ComponentBasicProps {
34
+ /**
35
+ * Identifier applied to the native ViewPager root.
36
+ * @zh 应用于原生 ViewPager 根节点的标识符。
37
+ * @Android
38
+ * @iOS
39
+ */
40
+ id?: string;
41
+ /**
42
+ * Data rendered as pages. ViewPager creates one direct native
43
+ * viewpager-item child for every entry.
44
+ * @zh 页面数据。ViewPager 为每条数据创建一个直接的原生 viewpager-item 子节点。
45
+ * @Android
46
+ * @iOS
47
+ */
48
+ data: readonly T[];
49
+ /**
50
+ * Return a stable, unique key for an entry. When omitted, the item index is
51
+ * used. Provide this function when items can be inserted, removed, or reordered.
52
+ * @zh 返回条目的稳定唯一键。不传时使用条目索引;当条目可能插入、删除或重排时请提供此函数。
53
+ * @docTypeFallback (item: T, index: number) => string | number
54
+ * @Android
55
+ * @iOS
56
+ */
57
+ getItemKey?: (item: T, index: number) => string | number;
58
+ /**
59
+ * Render page content. Selection state is intentionally not passed, so a
60
+ * native swipe does not require React to rerender page content.
61
+ * @zh 渲染页面内容。此函数有意不传入选中状态,因此原生滑动无需让 React 重新渲染页面内容。
62
+ * @docTypeFallback (item: T, index: number) => ReactNode
63
+ * @Android
64
+ * @iOS
65
+ */
66
+ children: (item: T, index: number) => ReactNode;
67
+ /**
68
+ * Initial page index. Later changes are ignored; use ref.scrollToPage to navigate.
69
+ * @defaultValue 0
70
+ * @zh 初始页面索引,后续修改不生效。使用 ref.scrollToPage 切换页面。
71
+ * @Android
72
+ * @iOS
73
+ */
74
+ initialSelectIndex?: number;
75
+ /**
76
+ * Exposure-driven lazy rendering. The initial page renders immediately;
77
+ * other pages render when their placeholders enter the configured exposure
78
+ * area. Rendered pages stay mounted. Omit this prop to render every page.
79
+ * @zh 基于曝光的懒渲染。初始页面立即渲染,其他页面在占位节点进入配置的曝光区域时渲染;已渲染页面保持挂载。不传时渲染全部页面。
80
+ * @Android
81
+ * @iOS
82
+ */
83
+ lazyOptions?: ViewPagerLazyOptions;
84
+ /**
85
+ * Class name applied to every generated viewpager-item.
86
+ * @zh 应用于每个自动生成的 viewpager-item 的类名。
87
+ * @Android
88
+ * @iOS
89
+ */
90
+ itemClassName?: string;
91
+ /**
92
+ * Style applied to every generated viewpager-item.
93
+ * @zh 应用于每个自动生成的 viewpager-item 的样式。
94
+ * @Android
95
+ * @iOS
96
+ */
97
+ itemStyle?: ComponentBasicProps['style'];
98
+ /**
99
+ * Native props for an individual generated item. Its class name is added to
100
+ * itemClassName; its style overrides matching itemStyle properties. The
101
+ * item's key, ref, and children are managed by ViewPager.
102
+ * @zh 单个自动生成条目的原生属性。类名与 itemClassName 合并;样式覆盖 itemStyle 的同名属性。条目的 key、ref 和 children 由 ViewPager 管理。
103
+ * @docTypeFallback (item: T, index: number) => ViewPagerItemProps
104
+ * @Android
105
+ * @iOS
106
+ */
107
+ getItemProps?: (item: T, index: number) => ViewPagerItemProps;
108
+ /**
109
+ * Enable horizontal swipe gestures.
110
+ * @defaultValue true
111
+ * @zh 启用水平滑动手势。
112
+ * @Android
113
+ * @iOS
114
+ */
115
+ enableScroll?: boolean;
116
+ /**
117
+ * Enable the native spring effect where supported.
118
+ * @defaultValue true
119
+ * @zh 在支持的平台启用原生回弹效果。
120
+ * @Android
121
+ * @iOS
122
+ */
123
+ bounces?: boolean;
124
+ /**
125
+ * Native pager attributes not managed by the component.
126
+ * @zh 组件未管理的原生分页器属性。
127
+ * @Android
128
+ * @iOS
129
+ */
130
+ viewpagerProps?: Omit<NativeViewPagerProps, 'children' | 'ref' | 'id' | 'className' | 'style' | 'initial-select-index' | 'align-width' | 'enable-scroll' | 'allow-horizontal-gesture' | 'bounces' | 'keep-item-view' | 'bindchange' | 'bindwillchange' | 'bindoffsetchange' | 'main-thread:bindchange' | 'main-thread:bindwillchange' | 'main-thread:bindoffsetchange'>;
131
+ /**
132
+ * Native page completion event. Read the selected index from event.detail.index.
133
+ * @zh 原生页面切换完成事件,从 event.detail.index 读取选中索引。
134
+ * @Android
135
+ * @iOS
136
+ */
137
+ onPageChange?: (event: ViewPagerChangeEvent) => void;
138
+ /**
139
+ * Native event before a page transition completes. Read its data from event.detail.
140
+ * @zh 原生页面切换完成前事件,从 event.detail 读取数据。
141
+ * @Android
142
+ * @iOS
143
+ */
144
+ onPageWillChange?: (event: ViewPagerWillChangeEvent) => void;
145
+ /**
146
+ * Native scroll progress event. Read its data from event.detail.
147
+ * @zh 原生滚动进度事件,从 event.detail 读取数据。
148
+ * @Android
149
+ * @iOS
150
+ */
151
+ onOffsetChange?: (event: ViewPagerOffsetChangeEvent) => void;
152
+ /**
153
+ * Main-thread page completion handler. Use a main thread function.
154
+ * @zh 主线程页面切换完成回调,需使用主线程函数。
155
+ * @Android
156
+ * @iOS
157
+ */
158
+ 'main-thread:onPageChange'?: (event: ViewPagerChangeEvent) => void;
159
+ /**
160
+ * Main-thread page transition handler. Use a main thread function.
161
+ * @zh 主线程页面即将切换回调,需使用主线程函数。
162
+ * @Android
163
+ * @iOS
164
+ */
165
+ 'main-thread:onPageWillChange'?: (event: ViewPagerWillChangeEvent) => void;
166
+ /**
167
+ * Main-thread scroll progress handler. Use a main thread function.
168
+ * @zh 主线程滚动进度回调,需使用主线程函数。
169
+ * @Android
170
+ * @iOS
171
+ */
172
+ 'main-thread:onOffsetChange'?: (event: ViewPagerOffsetChangeEvent) => void;
173
+ }
174
+ //# 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 { };
@@ -0,0 +1,2 @@
1
+ export declare function normalizeIndex(index: number, count: number): number;
2
+ //# sourceMappingURL=utils.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAIA,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGnE"}
package/dist/utils.jsx ADDED
@@ -0,0 +1,7 @@
1
+ function normalizeIndex(index, count) {
2
+ if (!Number.isFinite(index) || 0 === count) return 0;
3
+ return Math.min(Math.max(Math.trunc(index), 0), count - 1);
4
+ }
5
+ export { normalizeIndex };
6
+
7
+ //# sourceMappingURL=utils.jsx.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"utils.jsx","sources":["../src/utils.ts"],"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\nexport function normalizeIndex(index: number, count: number): number {\n if (!Number.isFinite(index) || count === 0) return 0\n return Math.min(Math.max(Math.trunc(index), 0), count - 1)\n}\n"],"names":["normalizeIndex","index","count","Number","Math"],"mappings":"AAIO,SAASA,eAAeC,KAAa,EAAEC,KAAa;IACzD,IAAI,CAACC,OAAO,QAAQ,CAACF,UAAUC,AAAU,MAAVA,OAAa,OAAO;IACnD,OAAOE,KAAK,GAAG,CAACA,KAAK,GAAG,CAACA,KAAK,KAAK,CAACH,QAAQ,IAAIC,QAAQ;AAC1D"}
package/package.json CHANGED
@@ -1,14 +1,53 @@
1
1
  {
2
2
  "name": "@lynx-js/lynx-ui-view-pager",
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-view-pager"
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
+ "clsx": "^2.1.1",
28
+ "@lynx-js/lynx-ui-common": "3.139.0",
29
+ "@lynx-js/lynx-ui-lazy-component": "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,159 @@
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 { forwardRef, memo, useImperativeHandle, useRef } from '@lynx-js/react'
6
+ import type { ForwardedRef, ReactElement, ReactNode } from '@lynx-js/react'
7
+
8
+ import { LazyComponent } from '@lynx-js/lynx-ui-lazy-component'
9
+ import type { NodesRef } from '@lynx-js/types'
10
+ import { clsx } from 'clsx'
11
+
12
+ import type { ViewPagerProps, ViewPagerRef } from './types'
13
+ import { normalizeIndex } from './utils'
14
+
15
+ export type * from './types'
16
+
17
+ type ViewPagerComponent = <T>(
18
+ props: ViewPagerProps<T> & { ref?: ForwardedRef<ViewPagerRef> },
19
+ ) => ReactElement
20
+
21
+ interface DeferredPageContentProps {
22
+ item: unknown
23
+ index: number
24
+ renderItem: (item: unknown, index: number) => ReactNode
25
+ }
26
+
27
+ function DeferredPageContent(props: DeferredPageContentProps) {
28
+ return props.renderItem(props.item, props.index)
29
+ }
30
+
31
+ export const ViewPager = memo(forwardRef(ViewPagerImpl)) as ViewPagerComponent
32
+
33
+ function ViewPagerImpl<T>(
34
+ props: ViewPagerProps<T>,
35
+ ref: ForwardedRef<ViewPagerRef>,
36
+ ) {
37
+ const {
38
+ data,
39
+ getItemKey,
40
+ children,
41
+ initialSelectIndex = 0,
42
+ id,
43
+ className,
44
+ style,
45
+ itemClassName,
46
+ itemStyle,
47
+ getItemProps,
48
+ viewpagerProps,
49
+ enableScroll = true,
50
+ bounces = true,
51
+ lazyOptions,
52
+ onPageChange,
53
+ onPageWillChange,
54
+ onOffsetChange,
55
+ 'main-thread:onPageChange': onPageChangeMT,
56
+ 'main-thread:onPageWillChange': onPageWillChangeMT,
57
+ 'main-thread:onOffsetChange': onOffsetChangeMT,
58
+ } = props
59
+ const initialIndex = useRef(initialSelectIndex)
60
+ const nativeRef = useRef<NodesRef>(null)
61
+ const countRef = useRef(data.length)
62
+ countRef.current = data.length
63
+ const normalizedInitialIndex = normalizeIndex(
64
+ initialIndex.current,
65
+ data.length,
66
+ )
67
+ const initialItemKey = useRef<string | number | undefined>(undefined)
68
+ if (initialItemKey.current === undefined && data.length > 0) {
69
+ initialItemKey.current = getItemKey?.(
70
+ data[normalizedInitialIndex],
71
+ normalizedInitialIndex,
72
+ ) ?? normalizedInitialIndex
73
+ }
74
+
75
+ useImperativeHandle(ref, () => ({
76
+ scrollToPage(next, smooth, success, fail) {
77
+ if (countRef.current === 0) return
78
+ nativeRef.current?.invoke({
79
+ method: 'selectTab',
80
+ params: {
81
+ index: normalizeIndex(next, countRef.current),
82
+ smooth: smooth ?? true,
83
+ },
84
+ success,
85
+ fail,
86
+ }).exec()
87
+ },
88
+ }))
89
+
90
+ const renderItem = children as (item: unknown, index: number) => ReactNode
91
+ const keepItemView = lazyOptions?.enableLazy === true
92
+ // Lynx can invoke an undefined native event binding during a swipe.
93
+ const eventProps = {
94
+ ...(onPageChange && { bindchange: onPageChange }),
95
+ ...(onPageWillChange && { bindwillchange: onPageWillChange }),
96
+ ...(onOffsetChange && { bindoffsetchange: onOffsetChange }),
97
+ ...(onPageChangeMT && { 'main-thread:bindchange': onPageChangeMT }),
98
+ ...(onPageWillChangeMT && {
99
+ 'main-thread:bindwillchange': onPageWillChangeMT,
100
+ }),
101
+ ...(onOffsetChangeMT && {
102
+ 'main-thread:bindoffsetchange': onOffsetChangeMT,
103
+ }),
104
+ }
105
+
106
+ return (
107
+ <viewpager
108
+ {...viewpagerProps}
109
+ ref={nativeRef}
110
+ id={id}
111
+ className={className}
112
+ style={{ width: '100%', display: 'flex', flexDirection: 'row', ...style }}
113
+ initial-select-index={normalizedInitialIndex}
114
+ align-width={true}
115
+ enable-scroll={enableScroll}
116
+ allow-horizontal-gesture={enableScroll}
117
+ bounces={bounces}
118
+ keep-item-view={keepItemView}
119
+ {...eventProps}
120
+ >
121
+ {data.map((item, index) => {
122
+ const itemKey = getItemKey?.(item, index) ?? index
123
+ const perItemProps = getItemProps?.(item, index)
124
+ return (
125
+ <viewpager-item
126
+ {...perItemProps}
127
+ key={itemKey}
128
+ className={clsx(itemClassName, perItemProps?.className)}
129
+ style={{
130
+ display: 'flex',
131
+ width: '100%',
132
+ flexShrink: 0,
133
+ ...itemStyle,
134
+ ...perItemProps?.style,
135
+ }}
136
+ >
137
+ {lazyOptions?.enableLazy && itemKey !== initialItemKey.current
138
+ ? (
139
+ <LazyComponent
140
+ pid={`lynx-ui-view-pager-${String(itemKey)}`}
141
+ scene={lazyOptions.scene}
142
+ estimatedStyle={{ width: '100%', height: '100%' }}
143
+ left={lazyOptions.exposureLeft}
144
+ right={lazyOptions.exposureRight}
145
+ >
146
+ <DeferredPageContent
147
+ item={item}
148
+ index={index}
149
+ renderItem={renderItem}
150
+ />
151
+ </LazyComponent>
152
+ )
153
+ : renderItem(item, index)}
154
+ </viewpager-item>
155
+ )
156
+ })}
157
+ </viewpager>
158
+ )
159
+ }
@@ -0,0 +1,226 @@
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 { ComponentBasicProps } from '@lynx-js/lynx-ui-common'
8
+ import type {
9
+ ViewPagerItemProps as NativeViewPagerItemProps,
10
+ ViewPagerProps as NativeViewPagerProps,
11
+ ViewPagerChangeEvent,
12
+ ViewPagerOffsetChangeEvent,
13
+ ViewPagerWillChangeEvent,
14
+ } from '@lynx-js/types'
15
+
16
+ export type {
17
+ ViewPagerChangeEvent,
18
+ ViewPagerOffsetChangeEvent,
19
+ ViewPagerWillChangeEvent,
20
+ }
21
+
22
+ export interface ViewPagerRef {
23
+ /**
24
+ * Slide to a page through the native node ref. Animation defaults to true.
25
+ * Indexes are clamped to available pages. Empty pagers ignore requests.
26
+ * Completion is reported through onPageChange; success confirms invocation.
27
+ * @zh 通过原生节点引用切换页面,默认使用动画。索引限制在有效范围内,空列表忽略请求。onPageChange 表示切换完成,success 表示调用成功。
28
+ * @Android
29
+ * @iOS
30
+ */
31
+ scrollToPage: (
32
+ index: number,
33
+ smooth?: boolean,
34
+ success?: (result: unknown) => void,
35
+ fail?: (result: unknown) => void,
36
+ ) => void
37
+ }
38
+
39
+ export type ViewPagerExposureMargin = `${number}px` | `${number}rpx`
40
+
41
+ export type ViewPagerItemProps =
42
+ & Omit<
43
+ NativeViewPagerItemProps,
44
+ 'key' | 'ref' | 'children' | 'style'
45
+ >
46
+ & { style?: ComponentBasicProps['style'] }
47
+
48
+ export type ViewPagerLazyOptions =
49
+ | {
50
+ /** Disable lazy rendering. @zh 禁用懒渲染。 */
51
+ enableLazy: false
52
+ }
53
+ | {
54
+ /** Enable exposure-driven lazy rendering for pages other than the initial page. @zh 为初始页面以外的页面启用基于曝光的懒渲染。 */
55
+ enableLazy: true
56
+ /** Exposure scene shared by this pager's lazy placeholders. It must be unique on the page. @zh 此分页器的懒加载占位节点共用的曝光场景,在页面内必须唯一。 */
57
+ scene: string
58
+ /** Extend or shrink the placeholder's left exposure boundary. @defaultValue 10px @zh 扩展或缩小占位节点的左侧曝光边界。 */
59
+ exposureLeft?: ViewPagerExposureMargin
60
+ /** Extend or shrink the placeholder's right exposure boundary. @defaultValue 10px @zh 扩展或缩小占位节点的右侧曝光边界。 */
61
+ exposureRight?: ViewPagerExposureMargin
62
+ }
63
+
64
+ export interface ViewPagerProps<T> extends ComponentBasicProps {
65
+ /**
66
+ * Identifier applied to the native ViewPager root.
67
+ * @zh 应用于原生 ViewPager 根节点的标识符。
68
+ * @Android
69
+ * @iOS
70
+ */
71
+ id?: string
72
+ /**
73
+ * Data rendered as pages. ViewPager creates one direct native
74
+ * viewpager-item child for every entry.
75
+ * @zh 页面数据。ViewPager 为每条数据创建一个直接的原生 viewpager-item 子节点。
76
+ * @Android
77
+ * @iOS
78
+ */
79
+ data: readonly T[]
80
+ /**
81
+ * Return a stable, unique key for an entry. When omitted, the item index is
82
+ * used. Provide this function when items can be inserted, removed, or reordered.
83
+ * @zh 返回条目的稳定唯一键。不传时使用条目索引;当条目可能插入、删除或重排时请提供此函数。
84
+ * @docTypeFallback (item: T, index: number) => string | number
85
+ * @Android
86
+ * @iOS
87
+ */
88
+ getItemKey?: (item: T, index: number) => string | number
89
+ /**
90
+ * Render page content. Selection state is intentionally not passed, so a
91
+ * native swipe does not require React to rerender page content.
92
+ * @zh 渲染页面内容。此函数有意不传入选中状态,因此原生滑动无需让 React 重新渲染页面内容。
93
+ * @docTypeFallback (item: T, index: number) => ReactNode
94
+ * @Android
95
+ * @iOS
96
+ */
97
+ children: (item: T, index: number) => ReactNode
98
+ /**
99
+ * Initial page index. Later changes are ignored; use ref.scrollToPage to navigate.
100
+ * @defaultValue 0
101
+ * @zh 初始页面索引,后续修改不生效。使用 ref.scrollToPage 切换页面。
102
+ * @Android
103
+ * @iOS
104
+ */
105
+ initialSelectIndex?: number
106
+ /**
107
+ * Exposure-driven lazy rendering. The initial page renders immediately;
108
+ * other pages render when their placeholders enter the configured exposure
109
+ * area. Rendered pages stay mounted. Omit this prop to render every page.
110
+ * @zh 基于曝光的懒渲染。初始页面立即渲染,其他页面在占位节点进入配置的曝光区域时渲染;已渲染页面保持挂载。不传时渲染全部页面。
111
+ * @Android
112
+ * @iOS
113
+ */
114
+ lazyOptions?: ViewPagerLazyOptions
115
+ /**
116
+ * Class name applied to every generated viewpager-item.
117
+ * @zh 应用于每个自动生成的 viewpager-item 的类名。
118
+ * @Android
119
+ * @iOS
120
+ */
121
+ itemClassName?: string
122
+ /**
123
+ * Style applied to every generated viewpager-item.
124
+ * @zh 应用于每个自动生成的 viewpager-item 的样式。
125
+ * @Android
126
+ * @iOS
127
+ */
128
+ itemStyle?: ComponentBasicProps['style']
129
+ /**
130
+ * Native props for an individual generated item. Its class name is added to
131
+ * itemClassName; its style overrides matching itemStyle properties. The
132
+ * item's key, ref, and children are managed by ViewPager.
133
+ * @zh 单个自动生成条目的原生属性。类名与 itemClassName 合并;样式覆盖 itemStyle 的同名属性。条目的 key、ref 和 children 由 ViewPager 管理。
134
+ * @docTypeFallback (item: T, index: number) => ViewPagerItemProps
135
+ * @Android
136
+ * @iOS
137
+ */
138
+ getItemProps?: (
139
+ item: T,
140
+ index: number,
141
+ ) => ViewPagerItemProps
142
+ /**
143
+ * Enable horizontal swipe gestures.
144
+ * @defaultValue true
145
+ * @zh 启用水平滑动手势。
146
+ * @Android
147
+ * @iOS
148
+ */
149
+ enableScroll?: boolean
150
+ /**
151
+ * Enable the native spring effect where supported.
152
+ * @defaultValue true
153
+ * @zh 在支持的平台启用原生回弹效果。
154
+ * @Android
155
+ * @iOS
156
+ */
157
+ bounces?: boolean
158
+ /**
159
+ * Native pager attributes not managed by the component.
160
+ * @zh 组件未管理的原生分页器属性。
161
+ * @Android
162
+ * @iOS
163
+ */
164
+ viewpagerProps?: Omit<
165
+ NativeViewPagerProps,
166
+ | 'children'
167
+ | 'ref'
168
+ | 'id'
169
+ | 'className'
170
+ | 'style'
171
+ | 'initial-select-index'
172
+ | 'align-width'
173
+ | 'enable-scroll'
174
+ | 'allow-horizontal-gesture'
175
+ | 'bounces'
176
+ | 'keep-item-view'
177
+ | 'bindchange'
178
+ | 'bindwillchange'
179
+ | 'bindoffsetchange'
180
+ | 'main-thread:bindchange'
181
+ | 'main-thread:bindwillchange'
182
+ | 'main-thread:bindoffsetchange'
183
+ >
184
+ /**
185
+ * Native page completion event. Read the selected index from event.detail.index.
186
+ * @zh 原生页面切换完成事件,从 event.detail.index 读取选中索引。
187
+ * @Android
188
+ * @iOS
189
+ */
190
+ onPageChange?: (event: ViewPagerChangeEvent) => void
191
+ /**
192
+ * Native event before a page transition completes. Read its data from event.detail.
193
+ * @zh 原生页面切换完成前事件,从 event.detail 读取数据。
194
+ * @Android
195
+ * @iOS
196
+ */
197
+ onPageWillChange?: (event: ViewPagerWillChangeEvent) => void
198
+ /**
199
+ * Native scroll progress event. Read its data from event.detail.
200
+ * @zh 原生滚动进度事件,从 event.detail 读取数据。
201
+ * @Android
202
+ * @iOS
203
+ */
204
+ onOffsetChange?: (event: ViewPagerOffsetChangeEvent) => void
205
+ /**
206
+ * Main-thread page completion handler. Use a main thread function.
207
+ * @zh 主线程页面切换完成回调,需使用主线程函数。
208
+ * @Android
209
+ * @iOS
210
+ */
211
+ 'main-thread:onPageChange'?: (event: ViewPagerChangeEvent) => void
212
+ /**
213
+ * Main-thread page transition handler. Use a main thread function.
214
+ * @zh 主线程页面即将切换回调,需使用主线程函数。
215
+ * @Android
216
+ * @iOS
217
+ */
218
+ 'main-thread:onPageWillChange'?: (event: ViewPagerWillChangeEvent) => void
219
+ /**
220
+ * Main-thread scroll progress handler. Use a main thread function.
221
+ * @zh 主线程滚动进度回调,需使用主线程函数。
222
+ * @Android
223
+ * @iOS
224
+ */
225
+ 'main-thread:onOffsetChange'?: (event: ViewPagerOffsetChangeEvent) => void
226
+ }
@@ -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'
package/src/utils.ts ADDED
@@ -0,0 +1,8 @@
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 function normalizeIndex(index: number, count: number): number {
6
+ if (!Number.isFinite(index) || count === 0) return 0
7
+ return Math.min(Math.max(Math.trunc(index), 0), count - 1)
8
+ }
@@ -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
+ }