zkit-ui 1.0.0

package/src/ui/Sheet/nativeBottom.web.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import type {
+  SheetCloseOptions,
+  SheetOpenOptions,
+  SheetState,
+} from './types';
+
+export type NativeBottomSheetOpenChangeDetails = {
+  reason: 'api' | 'backdrop' | 'back' | 'gesture' | 'system';
+  detentIndex: number;
+};
+
+export type NativeBottomSheetCloseCompleteDetails = {
+  reason: 'api' | 'backdrop' | 'back' | 'gesture' | 'system';
+  detentIndex: number;
+};
+
+export type NativeBottomSheetRef = {
+  open: (options?: SheetOpenOptions) => Promise<void>;
+  close: (options?: SheetCloseOptions) => Promise<void>;
+  snapTo: (detentIndex: number) => Promise<void>;
+  getState: () => SheetState;
+};
+
+export const NativeBottomSheet = React.forwardRef<NativeBottomSheetRef, Record<string, unknown>>(
+  function NativeBottomSheet(_, ref) {
+    React.useImperativeHandle(
+      ref,
+      () => ({
+        open: async () => {},
+        close: async () => {},
+        snapTo: async () => {},
+        getState: () => 'closed',
+      }),
+      []
+    );
+
+    return null;
+  }
+);

package/src/ui/Sheet/slots.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react';
+import { StyleSheet, View } from 'react-native';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { wp } from 'zkit-tools';
+import { useTheme } from '../../theme/useTheme';
+import { Text } from '../Text';
+import type {
+  SheetContentProps,
+  SheetFooterProps,
+  SheetHeaderProps,
+} from './types';
+
+export function SheetHeader({
+  title,
+  description,
+  children,
+  style,
+  ...props
+}: SheetHeaderProps) {
+  const theme = useTheme();
+
+  return (
+    <View {...props} style={[styles.header, style]}>
+      {children ?? (
+        <>
+          {title != null ? (
+            <Text
+              accessibilityRole="header"
+              numberOfLines={2}
+              size="lg"
+              weight="semibold"
+              style={{ color: theme.colors.onSurface }}
+            >
+              {title}
+            </Text>
+          ) : null}
+          {description != null ? (
+            <Text numberOfLines={3} size="sm" style={{ color: theme.colors.muted }}>
+              {description}
+            </Text>
+          ) : null}
+        </>
+      )}
+    </View>
+  );
+}
+
+export function SheetContent({ style, ...props }: SheetContentProps) {
+  return <View {...props} style={[styles.content, style]} />;
+}
+
+export function SheetFooter({ safeArea = true, style, ...props }: SheetFooterProps) {
+  const insets = useSafeAreaInsets();
+  const paddingBottom = safeArea ? Math.max(insets.bottom, wp(12)) : undefined;
+
+  return <View {...props} style={[styles.footer, paddingBottom != null && { paddingBottom }, style]} />;
+}
+
+const styles = StyleSheet.create({
+  header: {
+    gap: wp(4),
+    paddingHorizontal: wp(20),
+    paddingTop: wp(20),
+    paddingBottom: wp(12),
+  },
+  content: {
+    paddingHorizontal: wp(20),
+    paddingVertical: wp(16),
+  },
+  footer: {
+    gap: wp(10),
+    paddingHorizontal: wp(20),
+    paddingTop: wp(12),
+  },
+});

package/src/ui/Sheet/types.ts

@@ -0,0 +1,195 @@
+import type * as React from 'react';
+import type {
+  ColorValue,
+  StyleProp,
+  ViewProps,
+  ViewStyle,
+} from 'react-native';
+import type { EasingFunction, ReduceMotion } from 'react-native-reanimated';
+import type {
+  SheetDetent as NativeSheetDetent,
+  TrueSheetProps,
+} from '@lodev09/react-native-true-sheet';
+
+export type SheetPlacement = 'top' | 'right' | 'bottom' | 'left';
+export type SheetSize = 'auto' | 'sm' | 'md' | 'lg' | 'full' | `${number}%` | number;
+export type SheetState = 'closed' | 'opening' | 'open' | 'closing';
+export type SheetDetent =
+  | 'content'
+  | 'auto'
+  | 'medium'
+  | 'large'
+  | 'full'
+  | `${number}%`
+  | number;
+
+type ManagedNativeProps =
+  | 'name'
+  | 'children'
+  | 'detents'
+  | 'initialDetentIndex'
+  | 'initialDetentAnimated'
+  | 'dimmed'
+  | 'dimmedDetentIndex'
+  | 'dismissible'
+  | 'draggable'
+  | 'backgroundColor'
+  | 'cornerRadius'
+  | 'grabber'
+  | 'grabberOptions'
+  | 'maxContentHeight'
+  | 'maxContentWidth'
+  | 'header'
+  | 'headerStyle'
+  | 'footer'
+  | 'footerStyle'
+  | 'style'
+  | 'onDidPresent'
+  | 'onDidDismiss'
+  | 'onDetentChange';
+
+export type SheetNativeProps = Omit<TrueSheetProps, ManagedNativeProps>;
+
+export type SheetOpenReason = 'api';
+export type SheetCloseReason = 'api' | 'backdrop' | 'back' | 'gesture' | 'system';
+export type SheetOpenChangeReason = SheetOpenReason | SheetCloseReason;
+
+export type SheetAnimationConfig = {
+  duration?: number;
+  openDuration?: number;
+  closeDuration?: number;
+  easing?: EasingFunction;
+  reduceMotion?: ReduceMotion;
+};
+
+export type SheetSafeAreaEdges = {
+  top?: boolean;
+  right?: boolean;
+  bottom?: boolean;
+  left?: boolean;
+};
+
+export type SheetBackdropConfig = {
+  visible?: boolean;
+  dismissOnPress?: boolean;
+  color?: string;
+  opacity?: number;
+};
+
+export type SheetHandleConfig = {
+  width?: number;
+  height?: number;
+  topMargin?: number;
+  radius?: number;
+  color?: ColorValue;
+};
+
+export type SheetOpenOptions = {
+  detentIndex?: number;
+  animated?: boolean;
+};
+
+export type SheetCloseOptions = {
+  animated?: boolean;
+};
+
+export type SheetOpenChangeDetails = {
+  reason: SheetOpenChangeReason;
+  placement: SheetPlacement;
+  detentIndex: number | null;
+};
+
+export type SheetOpenCompleteDetails = {
+  placement: SheetPlacement;
+  detentIndex: number | null;
+};
+
+export type SheetCloseCompleteDetails = {
+  reason: SheetCloseReason;
+  placement: SheetPlacement;
+  detentIndex: number | null;
+};
+
+export type SheetDetentChangePayload = {
+  index: number;
+  detent: SheetDetent;
+  nativeDetent: NativeSheetDetent;
+  position: number;
+  placement: 'bottom';
+};
+
+export type SheetRenderContext = {
+  isOpen: boolean;
+  state: SheetState;
+  placement: SheetPlacement;
+  detentIndex: number | null;
+  open: (options?: SheetOpenOptions) => Promise<void>;
+  close: (options?: SheetCloseOptions) => Promise<void>;
+  snapTo: (detentIndex: number) => Promise<void>;
+};
+
+export type SheetRef = {
+  open: (options?: SheetOpenOptions) => Promise<void>;
+  close: (options?: SheetCloseOptions) => Promise<void>;
+  snapTo: (detentIndex: number) => Promise<void>;
+  getState: () => SheetState;
+};
+
+export type SheetSlot =
+  | React.ReactNode
+  | ((context: SheetRenderContext) => React.ReactNode);
+
+export type SheetProps = {
+  placement?: SheetPlacement;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean, details: SheetOpenChangeDetails) => void;
+  onOpenComplete?: (details: SheetOpenCompleteDetails) => void;
+  onCloseComplete?: (details: SheetCloseCompleteDetails) => void;
+
+  disabled?: boolean;
+  dismissible?: boolean;
+  draggable?: boolean;
+  backdrop?: boolean | SheetBackdropConfig;
+
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  header?: SheetSlot;
+  footer?: SheetSlot;
+  children?: SheetSlot;
+
+  size?: SheetSize;
+  safeArea?: boolean | SheetSafeAreaEdges;
+  detents?: readonly SheetDetent[];
+  detentIndex?: number;
+  defaultDetentIndex?: number;
+  onDetentChange?: (index: number, payload: SheetDetentChangePayload) => void;
+  nativeProps?: SheetNativeProps;
+
+  backgroundColor?: ColorValue;
+  cornerRadius?: number;
+  maxHeight?: number;
+  maxWidth?: number;
+  handle?: boolean | SheetHandleConfig;
+  animation?: SheetAnimationConfig | false;
+  dragCloseThreshold?: number;
+  dragVelocityThreshold?: number;
+  style?: StyleProp<ViewStyle>;
+  headerStyle?: StyleProp<ViewStyle>;
+  footerStyle?: StyleProp<ViewStyle>;
+
+  testID?: ViewProps['testID'];
+  accessibilityLabel?: ViewProps['accessibilityLabel'];
+  backdropAccessibilityLabel?: string;
+};
+
+export type SheetHeaderProps = ViewProps & {
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+};
+
+export type SheetContentProps = ViewProps;
+
+export type SheetFooterProps = ViewProps & {
+  safeArea?: boolean;
+};

package/src/ui/SliderCaptcha/README.md

@@ -0,0 +1,61 @@
+# SliderCaptcha
+
+滑动拼图验证码弹层组件，负责通用的 UI、拖拽映射、校验反馈和失败后自动刷新。
+
+## 设计边界
+
+- `zkit-ui` 负责：
+  - 弹层展示
+  - 图片缩放与坐标换算
+  - 滑块拖拽与释放触发校验
+  - `loading / verifying / success / error` 状态反馈
+  - 校验失败后的自动重载
+- 业务方负责：
+  - 拉取验证码题目
+  - 调用业务接口做验证
+  - 成功后的页面跳转、倒计时、埋点等副作用
+
+## 最小示例
+
+```tsx
+import * as React from 'react';
+import { SliderCaptcha, type SliderCaptchaChallenge } from 'zkit-ui';
+
+type LoginCaptchaChallenge = SliderCaptchaChallenge & {
+  nonceStr: string;
+};
+
+function Example() {
+  const [visible, setVisible] = React.useState(false);
+
+  return (
+    <SliderCaptcha<LoginCaptchaChallenge>
+      visible={visible}
+      onClose={() => setVisible(false)}
+      loadChallenge={async () => {
+        const res = await fetchCaptcha();
+        return {
+          nonceStr: res.nonceStr,
+          backgroundImage: res.canvasSrc,
+          blockImage: res.blockSrc,
+          blockY: res.blockY,
+          originalWidth: 320,
+          originalHeight: 220,
+          blockWidth: 50,
+          blockHeight: 50,
+        };
+      }}
+      verifyChallenge={async ({ challenge, offsetX }) => {
+        const res = await verifyCaptcha({
+          nonceStr: challenge.nonceStr,
+          blockX: offsetX,
+        });
+        return res.ok;
+      }}
+      onVerified={() => {
+        setVisible(false);
+      }}
+    />
+  );
+}
+```