wn-native-ui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# 更新记录
+
+## 0.1.0
+
+- 品牌统一为 WN UI，npm 包名为 wn-native-ui，同步展示项目、导入路径及安装文档。
+
+- 提取 30 组 React Native 公共组件，保留原交互与默认视觉。
+- 移除原项目的路径别名，提供包入口、组件子路径和 token 导出。
+- 增加 ES Module、TypeScript 声明、npm 打包和格式化配置。
+- 展示应用独立放入 example，通过实际 tgz 安装组件库。
+- 原始提取文件保存在 archive，不随 npm 包分发。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# WN UI
+
+30 组可复用的 React Native 公共组件，提供 TypeScript 类型、统一入口、单组件子路径和默认 UI token。不依赖原项目的路由、接口、登录态或 `@/` 路径别名。
+
+包名 `wn-native-ui`、版本 `0.1.0`，目前仅用于本地安装，尚未发布到 npm。`private: true` 防止误发布；`UNLICENSED` 表示尚未授权公开分发，并非开源许可证。
+
+## 在其他项目安装
+
+适用于 Expo / React Native 工程，不是普通 React DOM 组件库。本版沿用源项目依赖范围：Expo SDK 56、React 19.2.3、React Native 0.85.3。其他版本需单独验证，不建议使用 `--force` 跳过依赖冲突。
+
+在已有的兼容 Expo 工程根目录执行：
+
+```powershell
+npx expo install expo-document-picker expo-image expo-image-picker expo-linear-gradient react-native-safe-area-context react-native-svg
+npm install "D:/code/compontent/artifacts/wn-native-ui-0.1.0.tgz"
+```
+
+也可将 `.tgz` 复制到目标项目的 `vendor/` 后执行：
+
+```bash
+npm install ./vendor/wn-native-ui-0.1.0.tgz
+```
+
+推荐安装 tgz，避免本地目录链接导致 React 多实例。不要从公共 npm 仓库直接安装同名包：此包尚未发布，同名包可能属于其他人。
+
+裸 React Native 工程需要先接入 Expo Modules，并安装兼容的原生依赖。iOS 按宿主流程安装 Pods；新增原生模块或更改相机/相册权限后需要重新构建 App。
+
+## 最小示例
+
+```tsx
+import { View } from 'react-native';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { Button, Toast, ToastProvider } from 'wn-native-ui';
+
+export default function App() {
+  return (
+    <SafeAreaProvider>
+      <ToastProvider>
+        <View style={{ flex: 1, justifyContent: 'center', padding: 24 }}>
+          <Button onPress={() => Toast.success('保存成功')}>保存</Button>
+        </View>
+      </ToastProvider>
+    </SafeAreaProvider>
+  );
+}
+```
+
+宿主已有 SafeAreaProvider 时沿用现有 Provider。ToastProvider 全局挂载一次。库不要求使用 Expo Router，路由依赖仅属于展示项目。
+
+统一入口与子路径都可使用：
+
+```tsx
+import { Button, Form, Input, type ButtonProps } from 'wn-native-ui';
+import { DatePicker, type DatePickerProps } from 'wn-native-ui/DatePicker';
+import { uiTokens } from 'wn-native-ui/tokens';
+```
+
+子路径只公开组件入口，不公开内部实现。单组件导入不意味着可以忽略本版声明的 peerDependencies。
+
+## 宿主责任与兼容边界
+
+- 业务数据、接口请求和持久化由宿主提供。
+- Upload 的 `upload` 回调由宿主对接真实上传服务；不提供时选择结果保留为待上传。展示页的 simulateUpload 仅供演示。
+- 相机、相册、文件选择依赖 Expo 模块；权限文案、系统授权和原生构建由宿主配置。图片选择器插件配置可参考 `example/app.json`。
+- 保留原组件默认视觉，可通过已暴露的 style、titleStyle 等属性调整。uiTokens 用于读取默认样式，本版没有运行时主题切换，不应修改 token 对象来切换主题。
+- 默认文案含中文，是否可以覆盖取决于各组件 Props；本版未完成完整国际化。
+- Web 需要 React Native Web。SSR、Node 服务端直接渲染及纯 React DOM 项目不在验证范围。
+
+Props、事件与示例见 [组件目录](src/components/README.md) 及各组件的 README。
+
+## 开发和打包
+
+本次工具环境为 Node.js 22.22.0 / npm 10.9.4。
+
+```bash
+npm ci
+npm run format
+npm run format:check
+npm run typecheck
+npm run build
+npm run verify:package
+npm pack --dry-run
+```
+
+生成安装包：
+
+```powershell
+New-Item -ItemType Directory -Path artifacts -Force
+npm pack --pack-destination artifacts
+```
+
+prepack 自动执行类型检查、构建和包入口检查。安装 tgz 不会在使用方执行组件库构建。lib 包含 ES Module 与 `.d.ts` 声明；运行时依赖由宿主提供，React 没有打进产物。
+
+## 展示项目
+
+先生成 tgz，再执行：
+
+```bash
+cd example
+npm ci
+npm run typecheck
+npm run android
+```
+
+macOS / Xcode 环境可运行 `npm run ios`。`npm run web` 用于 Web 布局检查，示例固定使用端口 5188，请先确保可用。
+
+示例使用 `file:../artifacts/wn-native-ui-0.1.0.tgz` 安装真实包，不使用指向库源码的别名。库更新后需要重新打包并更新安装；正式维护时递增版本，同时更新示例的 tgz 路径和锁文件，避免同版本缓存。
+
+## 目录
+
+```text
+src/index.ts               公共包入口
+src/components/            30 组组件与文档
+src/ui/tokens.ts           默认样式 token
+lib/                      自动生成的 JS 与类型声明
+example/                  独立 Expo 展示应用
+scripts/verify-package.mjs 包入口、路径及依赖检查
+artifacts/                npm 安装包
+archive/                  原始提取 ZIP、清单、依赖记录和说明
+```
+
+archive 的 SHA-256 清单仅对应原始备份，不对应整理后的文件。example、archive、artifacts、锁文件和开发脚本不随 npm 包分发。
+
+## 发布准备
+
+发布前确定自己拥有的 npm 包名或 scope、分发范围和许可证，再调整 private、license、包名及示例中的导入路径。本次没有登录或发布到 npm。
+
+构建参考 [React Native Builder Bob](https://oss.callstack.com/react-native-builder-bob/build)，打包参考 [npm pack](https://docs.npmjs.com/cli/v11/commands/npm-pack/)。

package/lib/module/components/Avatar/Avatar.js

@@ -0,0 +1,131 @@
+"use strict";
+
+import { useMemo, useState } from 'react';
+import { Image, Text, View } from 'react-native';
+import { styles } from "./styles.js";
+import { jsx as _jsx } from "react/jsx-runtime";
+export function Avatar({
+  accessibilityLabel,
+  decorative = false,
+  fallback,
+  label,
+  shape = 'circle',
+  size = 'large',
+  source,
+  src,
+  style,
+  testID,
+  textStyle,
+  tone = 'accent'
+}) {
+  const [failedImageKey, setFailedImageKey] = useState('');
+  const imageSource = source ?? (src ? {
+    uri: src
+  } : undefined);
+  const imageSourceKey = useMemo(() => getImageSourceKey(source, src), [source, src]);
+  const sizeValue = resolveAvatarSize(size);
+  const radius = shape === 'circle' ? sizeValue / 2 : resolveRoundedRadius(sizeValue);
+  const textMetrics = resolveTextMetrics(sizeValue);
+  const initial = getAvatarInitial(fallback ?? label);
+  const showImage = Boolean(imageSource && failedImageKey !== imageSourceKey);
+  return /*#__PURE__*/_jsx(View, {
+    accessibilityElementsHidden: decorative,
+    accessibilityLabel: decorative ? undefined : accessibilityLabel ?? getAvatarAccessibilityLabel(label),
+    accessibilityRole: decorative ? undefined : 'image',
+    accessible: !decorative,
+    importantForAccessibility: decorative ? 'no-hide-descendants' : 'auto',
+    style: [styles.root, stylesByTone[tone].root, {
+      borderRadius: radius,
+      height: sizeValue,
+      width: sizeValue
+    }, style],
+    testID: testID,
+    children: showImage && imageSource ? /*#__PURE__*/_jsx(Image, {
+      accessibilityIgnoresInvertColors: true,
+      onError: () => setFailedImageKey(imageSourceKey),
+      resizeMode: "cover",
+      source: imageSource,
+      style: [styles.image, {
+        borderRadius: radius
+      }]
+    }) : /*#__PURE__*/_jsx(Text, {
+      allowFontScaling: false,
+      numberOfLines: 1,
+      style: [styles.text, stylesByTone[tone].text, textMetrics, textStyle],
+      children: initial
+    })
+  });
+}
+const stylesByTone = {
+  accent: {
+    root: styles.accentRoot,
+    text: styles.accentText
+  },
+  neutral: {
+    root: styles.neutralRoot,
+    text: styles.neutralText
+  }
+};
+function resolveAvatarSize(size) {
+  if (typeof size === 'number') {
+    return Math.max(20, size);
+  }
+  const sizes = {
+    large: 52,
+    medium: 40,
+    profile: 72,
+    small: 32
+  };
+  return sizes[size];
+}
+function resolveRoundedRadius(size) {
+  if (size >= 52) {
+    return 18;
+  }
+  if (size >= 40) {
+    return 14;
+  }
+  return 12;
+}
+function resolveTextMetrics(size) {
+  if (size >= 64) {
+    return styles.profileText;
+  }
+  if (size >= 52) {
+    return styles.largeText;
+  }
+  if (size >= 40) {
+    return styles.mediumText;
+  }
+  return styles.smallText;
+}
+function getAvatarInitial(value) {
+  const normalized = value?.trim();
+  if (!normalized) {
+    return '学';
+  }
+  return Array.from(normalized)[0] ?? '学';
+}
+function getAvatarAccessibilityLabel(label) {
+  const normalized = label?.trim();
+  if (!normalized) {
+    return '头像';
+  }
+  return `${normalized}头像`;
+}
+function getImageSourceKey(source, src) {
+  if (src) {
+    return src;
+  }
+  if (!source) {
+    return '';
+  }
+  if (typeof source === 'number') {
+    return String(source);
+  }
+  try {
+    return JSON.stringify(source);
+  } catch {
+    return 'source';
+  }
+}

package/lib/module/components/Avatar/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+export { Avatar } from "./Avatar.js";

package/lib/module/components/Avatar/styles.js

@@ -0,0 +1,49 @@
+"use strict";
+
+import { StyleSheet } from 'react-native';
+import { uiTokens as token } from "../../ui/tokens.js";
+export const styles = StyleSheet.create({
+  accentRoot: {
+    backgroundColor: token.color.bgSelected
+  },
+  accentText: {
+    color: token.color.tintDefault
+  },
+  image: {
+    height: '100%',
+    width: '100%'
+  },
+  largeText: {
+    fontSize: 20,
+    lineHeight: 25
+  },
+  mediumText: {
+    fontSize: 16,
+    lineHeight: 21
+  },
+  neutralRoot: {
+    backgroundColor: token.color.bgDisabled
+  },
+  neutralText: {
+    color: token.color.labelSecondary
+  },
+  profileText: {
+    fontSize: 26,
+    lineHeight: 32
+  },
+  root: {
+    alignItems: 'center',
+    flexShrink: 0,
+    justifyContent: 'center',
+    overflow: 'hidden'
+  },
+  smallText: {
+    fontSize: 13,
+    lineHeight: 18
+  },
+  text: {
+    fontWeight: '700',
+    includeFontPadding: false,
+    textAlign: 'center'
+  }
+});

package/lib/module/components/BottomActionBar/BottomActionBar.js

@@ -0,0 +1,43 @@
+"use strict";
+
+import { View } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { Button } from "../Button/index.js";
+import { styles } from "./styles.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+function ActionButton({
+  action,
+  defaultVariant
+}) {
+  return /*#__PURE__*/_jsx(View, {
+    style: styles.action,
+    children: /*#__PURE__*/_jsx(Button, {
+      accessibilityHint: action.accessibilityHint,
+      disabled: action.disabled,
+      loading: action.loading,
+      onPress: action.onPress,
+      variant: action.variant ?? defaultVariant,
+      children: action.label
+    })
+  });
+}
+export function BottomActionBar({
+  primary,
+  secondary,
+  style
+}) {
+  return /*#__PURE__*/_jsx(SafeAreaView, {
+    edges: ['bottom'],
+    style: [styles.safeArea, style],
+    children: /*#__PURE__*/_jsxs(View, {
+      style: styles.actions,
+      children: [secondary ? /*#__PURE__*/_jsx(ActionButton, {
+        action: secondary,
+        defaultVariant: "secondary"
+      }) : null, /*#__PURE__*/_jsx(ActionButton, {
+        action: primary,
+        defaultVariant: "primary"
+      })]
+    })
+  });
+}

package/lib/module/components/BottomActionBar/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+export { BottomActionBar } from "./BottomActionBar.js";

package/lib/module/components/BottomActionBar/styles.js

@@ -0,0 +1,22 @@
+"use strict";
+
+import { StyleSheet } from 'react-native';
+import { uiTokens as token } from "../../ui/tokens.js";
+export const styles = StyleSheet.create({
+  action: {
+    flex: 1
+  },
+  actions: {
+    flexDirection: 'row',
+    gap: token.space.s12,
+    paddingHorizontal: token.space.s16,
+    paddingTop: token.space.s8
+  },
+  safeArea: {
+    alignSelf: 'stretch',
+    backgroundColor: token.color.bgSecondary,
+    borderTopColor: token.color.separator,
+    borderTopWidth: 1,
+    paddingBottom: token.space.s8
+  }
+});

package/lib/module/components/BottomSheet/BottomSheet.js

@@ -0,0 +1,103 @@
+"use strict";
+
+import { ActivityIndicator, KeyboardAvoidingView, Modal, Platform, Pressable, ScrollView, Text, View } from 'react-native';
+import { SafeAreaView } from 'react-native-safe-area-context';
+import { uiTokens as token } from "../../ui/tokens.js";
+import { styles } from "./styles.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function BottomSheet({
+  cancelText = '取消',
+  children,
+  confirmDisabled = false,
+  confirmLoading = false,
+  confirmText = '确定',
+  contentContainerStyle,
+  header,
+  onCancel,
+  onClose,
+  onConfirm,
+  onDismiss,
+  scrollable = true,
+  title,
+  visible
+}) {
+  const hasConfirmation = Boolean(onConfirm);
+  const confirmUnavailable = confirmDisabled || confirmLoading;
+  const content = scrollable ? /*#__PURE__*/_jsx(ScrollView, {
+    contentContainerStyle: [styles.content, contentContainerStyle],
+    keyboardShouldPersistTaps: "handled",
+    showsVerticalScrollIndicator: false,
+    style: styles.scrollView,
+    children: children
+  }) : /*#__PURE__*/_jsx(View, {
+    style: [styles.content, contentContainerStyle],
+    children: children
+  });
+  return /*#__PURE__*/_jsx(Modal, {
+    animationType: "slide",
+    onDismiss: onDismiss,
+    onRequestClose: onClose,
+    presentationStyle: "overFullScreen",
+    statusBarTranslucent: true,
+    transparent: true,
+    visible: visible,
+    children: /*#__PURE__*/_jsxs(KeyboardAvoidingView, {
+      accessibilityViewIsModal: true,
+      behavior: Platform.OS === 'ios' ? 'padding' : undefined,
+      style: styles.modalRoot,
+      children: [/*#__PURE__*/_jsx(Pressable, {
+        accessibilityLabel: `关闭${title}`,
+        accessibilityRole: "button",
+        onPress: onClose,
+        style: styles.backdrop
+      }), /*#__PURE__*/_jsxs(SafeAreaView, {
+        edges: ['bottom'],
+        style: styles.sheet,
+        children: [/*#__PURE__*/_jsx(View, {
+          style: styles.grabberArea,
+          children: /*#__PURE__*/_jsx(View, {
+            style: styles.grabber
+          })
+        }), header ?? /*#__PURE__*/_jsxs(View, {
+          style: styles.header,
+          children: [hasConfirmation ? /*#__PURE__*/_jsx(Pressable, {
+            accessibilityRole: "button",
+            onPress: onCancel ?? onClose,
+            style: ({
+              pressed
+            }) => [styles.action, pressed && styles.pressed],
+            children: /*#__PURE__*/_jsx(Text, {
+              style: styles.cancelText,
+              children: cancelText
+            })
+          }) : /*#__PURE__*/_jsx(View, {
+            style: styles.action
+          }), /*#__PURE__*/_jsx(Text, {
+            accessibilityRole: "header",
+            numberOfLines: 1,
+            style: styles.title,
+            children: title
+          }), /*#__PURE__*/_jsx(Pressable, {
+            accessibilityRole: "button",
+            accessibilityState: {
+              busy: confirmLoading,
+              disabled: hasConfirmation && confirmUnavailable
+            },
+            disabled: hasConfirmation && confirmUnavailable,
+            onPress: onConfirm ?? onClose,
+            style: ({
+              pressed
+            }) => [styles.action, styles.actionEnd, hasConfirmation && confirmUnavailable && styles.disabled, pressed && styles.pressed],
+            children: confirmLoading ? /*#__PURE__*/_jsx(ActivityIndicator, {
+              color: token.color.tintDefault,
+              size: "small"
+            }) : /*#__PURE__*/_jsx(Text, {
+              style: styles.confirmText,
+              children: hasConfirmation ? confirmText : '关闭'
+            })
+          })]
+        }), content]
+      })]
+    })
+  });
+}

package/lib/module/components/BottomSheet/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+export { BottomSheet } from "./BottomSheet.js";

package/lib/module/components/BottomSheet/styles.js

@@ -0,0 +1,84 @@
+"use strict";
+
+import { StyleSheet } from 'react-native';
+import { uiTokens as token } from "../../ui/tokens.js";
+export const styles = StyleSheet.create({
+  action: {
+    alignItems: 'flex-start',
+    justifyContent: 'center',
+    minHeight: token.size.minTouch,
+    minWidth: token.size.minTouch,
+    paddingHorizontal: token.space.s16
+  },
+  actionEnd: {
+    alignItems: 'flex-end'
+  },
+  backdrop: {
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0
+  },
+  cancelText: {
+    color: token.color.labelSecondary,
+    ...token.type.subheadline
+  },
+  confirmText: {
+    color: token.color.tintPressed,
+    ...token.type.subheadline,
+    fontWeight: '600'
+  },
+  content: {
+    gap: token.space.s12,
+    paddingBottom: token.space.s16,
+    paddingHorizontal: token.space.s16
+  },
+  disabled: {
+    opacity: token.opacity.disabled
+  },
+  grabber: {
+    backgroundColor: token.color.labelTertiary,
+    borderRadius: token.radius.capsule,
+    height: token.size.bottomSheetGrabberHeight,
+    opacity: token.opacity.disabled,
+    width: token.size.bottomSheetGrabberWidth
+  },
+  grabberArea: {
+    alignItems: 'center',
+    minHeight: token.space.s20,
+    paddingTop: token.space.s8
+  },
+  header: {
+    alignItems: 'center',
+    flexDirection: 'row',
+    minHeight: token.size.minTouch
+  },
+  modalRoot: {
+    backgroundColor: token.color.overlayScrim,
+    flex: 1,
+    justifyContent: 'flex-end'
+  },
+  pressed: {
+    opacity: token.opacity.pressed
+  },
+  scrollView: {
+    flexShrink: 1
+  },
+  sheet: {
+    alignSelf: 'center',
+    backgroundColor: token.color.bgSecondary,
+    borderTopLeftRadius: token.radius.large,
+    borderTopRightRadius: token.radius.large,
+    maxHeight: '86%',
+    maxWidth: token.size.bottomSheetMaxWidth,
+    overflow: 'hidden',
+    width: '100%'
+  },
+  title: {
+    color: token.color.labelPrimary,
+    flex: 1,
+    textAlign: 'center',
+    ...token.type.headline
+  }
+});

package/lib/module/components/Button/Button.js

@@ -0,0 +1,38 @@
+"use strict";
+
+import { ActivityIndicator, Pressable, Text } from 'react-native';
+import { uiTokens as token } from "../../ui/tokens.js";
+import { styles } from "./styles.js";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+export function Button({
+  accessibilityState,
+  children,
+  disabled = false,
+  loading = false,
+  style,
+  variant = 'primary',
+  ...pressableProps
+}) {
+  const isDisabled = disabled || loading;
+  const spinnerColor = variant === 'secondary' ? token.color.tintDefault : token.color.onTint;
+  return /*#__PURE__*/_jsxs(Pressable, {
+    ...pressableProps,
+    accessibilityRole: "button",
+    accessibilityState: {
+      ...accessibilityState,
+      busy: loading,
+      disabled: isDisabled
+    },
+    disabled: isDisabled,
+    style: ({
+      pressed
+    }) => [styles.button, variant === 'primary' && styles.primary, variant === 'secondary' && styles.secondary, variant === 'destructive' && styles.destructive, isDisabled && styles.disabled, pressed && !isDisabled && styles.pressed, style],
+    children: [loading ? /*#__PURE__*/_jsx(ActivityIndicator, {
+      color: spinnerColor,
+      size: "small"
+    }) : null, /*#__PURE__*/_jsx(Text, {
+      style: [styles.label, variant === 'secondary' && styles.secondaryLabel, isDisabled && styles.disabledLabel],
+      children: children
+    })]
+  });
+}

package/lib/module/components/Button/index.js

@@ -0,0 +1,3 @@
+"use strict";
+
+export { Button } from "./Button.js";