@unif/react-native-design 0.1.0

package/src/components/ui/Card/index.ts

@@ -0,0 +1,2 @@
+export { Card } from './Card';
+export type { CardProps, CardVariant } from './types';

package/src/components/ui/Card/styles.ts

@@ -0,0 +1,33 @@
+import { StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import type { ColorTokens, ShadowTokens } from '../../../theme';
+import type { CardVariant } from './types';
+
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    base: {
+      backgroundColor: c.surface,
+      overflow: 'hidden',
+    },
+    flat: {},
+  });
+
+/**
+ * variant → 装饰样式映射(§8 返 style 值的 helper,合并入 styles.ts):
+ * - `default`:`s.card` 标准卡片阴影
+ * - `flat`:走 `styles.flat`(目前空,deprecated 等价 plain;保留以容纳未来差量)
+ * - `plain`:`undefined`(纯白底,装饰为零)
+ */
+export function variantToStyle(
+  v: CardVariant,
+  s: ShadowTokens,
+  styles: ReturnType<typeof makeStyles>
+): StyleProp<ViewStyle> {
+  switch (v) {
+    case 'default':
+      return s.card;
+    case 'flat':
+      return styles.flat;
+    case 'plain':
+      return undefined;
+  }
+}

package/src/components/ui/Card/types.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * Card **视觉变体**（控制装饰，跟 `bare` 是正交维度）：
+ * - `default`：白底 + 阴影 + 边框（标准卡片）
+ * - `plain`：仅白底（无阴影无边框，承载更轻量，如 chat 气泡内嵌组件）
+ * - `flat`：**deprecated** — 等价于 `plain`，新代码请用 `plain`。
+ */
+export type CardVariant = 'default' | 'flat' | 'plain';
+
+export type CardProps = {
+  /** Card 内容 */
+  children: ReactNode;
+  /** 视觉变体，默认 'default' */
+  variant?: CardVariant;
+  /** 自定义内边距（覆盖默认 padding） */
+  padding?: number;
+  /** 自定义圆角（覆盖默认 radius.md） */
+  borderRadius?: number;
+  /** 自定义边框色（覆盖默认 c.outline；仅 default/flat 有边框） */
+  borderColor?: string;
+  /** 自定义边框宽度（覆盖默认 1；仅 default/flat 有边框） */
+  borderWidth?: number;
+  /**
+   * 「裸壳」模式：把 padding 设为 0，children 紧贴 Card 边缘渲染。
+   *
+   * **跟 variant 是正交维度**：
+   *  - `variant` 控制装饰（阴影 / 边框 / 底色）
+   *  - `bare` 控制内边距（是否留白）
+   *
+   * 常用组合：
+   *  - 业务想自己控 padding 但保留卡片视觉 → `<Card variant="default" bare>`
+   *  - 业务要「完全朴素」（无装饰 + 无 padding）→ `<Card variant="plain" bare>`
+   */
+  bare?: boolean;
+  /** 额外样式覆盖 */
+  style?: StyleProp<ViewStyle>;
+  /** 测试 testID */
+  testID?: string;
+};

package/src/components/ui/Carousel/Carousel.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+import { Pressable, useWindowDimensions, View } from 'react-native';
+import ReanimatedCarousel, {
+  Pagination,
+} from 'react-native-reanimated-carousel';
+import { useSharedValue } from 'react-native-reanimated';
+import { space, useThemedStyles } from '../../../theme';
+import { makeCarouselStyles } from './styles';
+import type { CarouselProps } from './types';
+
+/** Carousel —— 包装 `react-native-reanimated-carousel@5.0.0-beta.5`。
+ *
+ *  dot indicator 走 `c.primary` token,使用库内置 `Pagination.Custom`
+ *  (`useSharedValue` + `onProgressChange` 驱动,re-render 全在 worklet 里)。
+ *
+ *  用 Pagination.Custom 而非 Basic:Basic 的 activeDot 用 translateX 推进
+ *  内层 fill,外壳宽度等于 dotStyle.width,activeDotStyle.width 只影响内层,
+ *  做不出"active 4 → 12 长条"。Custom 自己 interpolate width/height/bg。
+ */
+// T 约束 object —— `Pagination.Basic<T extends {}>` 需要 object
+export function Carousel<T extends object>({
+  items,
+  renderItem,
+  height,
+  itemWidth,
+  autoPlay,
+  showIndicator = true,
+  indicatorPosition = 'bottom',
+  onPressItem,
+  getAccessibilityLabel,
+  style,
+  testID,
+}: CarouselProps<T>): React.JSX.Element {
+  const { width: screenWidth } = useWindowDimensions();
+  const width = itemWidth ?? screenWidth;
+  const styles = useThemedStyles(makeCarouselStyles);
+  // Carousel `onProgressChange` 把 absoluteProgress 写进 shared value,Pagination 自动跟。
+  const progress = useSharedValue<number>(0);
+
+  // 'bottom' 模式给容器额外 +space[7] (=r(16)) 高度容纳独立行指示器;
+  // 与 dotsWrapBottom 的 paddingTop=space[3]+dot height space[1] 一起跟 r() 同步缩放。
+  // 'overlay-bottom-right' 不占额外高度。
+  const indicatorReservedHeight =
+    showIndicator && indicatorPosition === 'bottom' ? space['7'] : 0;
+
+  const data = items as T[];
+
+  return (
+    <View
+      style={[{ height: height + indicatorReservedHeight }, style]}
+      testID={testID}
+    >
+      <ReanimatedCarousel
+        // v5 把 width / height prop deprecate,迁到 style
+        style={{ width, height }}
+        data={data}
+        loop
+        autoPlay={!!autoPlay}
+        autoPlayInterval={autoPlay}
+        onProgressChange={progress}
+        renderItem={({ item, index }) => (
+          <Pressable
+            onPress={() => onPressItem?.(item, index)}
+            style={{ width, height }}
+            testID={`${testID ?? 'carousel'}-item-${index}`}
+            // 只在真正可点时声明 button 语义,纯展示型不标 button 避免读屏器误导
+            {...(onPressItem
+              ? {
+                  accessibilityRole: 'button' as const,
+                  accessibilityLabel:
+                    getAccessibilityLabel?.(item, index) ??
+                    `第 ${index + 1} 项`,
+                }
+              : null)}
+          >
+            {renderItem(item, index)}
+          </Pressable>
+        )}
+      />
+      {showIndicator && items.length > 1 ? (
+        <Pagination.Custom<T>
+          progress={progress}
+          data={data}
+          dotStyle={styles.dot}
+          activeDotStyle={styles.dotActive}
+          containerStyle={
+            indicatorPosition === 'overlay-bottom-right'
+              ? styles.dotsWrapOverlay
+              : styles.dotsWrapBottom
+          }
+        />
+      ) : null}
+    </View>
+  );
+}

package/src/components/ui/Carousel/index.ts

@@ -0,0 +1,2 @@
+export { Carousel } from './Carousel';
+export type { CarouselProps } from './types';

package/src/components/ui/Carousel/styles.ts

@@ -0,0 +1,41 @@
+import { StyleSheet } from 'react-native';
+import { r, radius, space, type ColorTokens } from '../../../theme';
+
+export const makeCarouselStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    /** 'bottom' 模式:独立行容器,覆盖 Pagination.Custom 默认的 `justifyContent: 'space-between'`
+     *  (否则 dot 横向撑开),让 dot 居中紧贴。 */
+    dotsWrapBottom: {
+      flexDirection: 'row',
+      justifyContent: 'center',
+      alignItems: 'center',
+      // 3pt 横间距:dot 单元 4pt + space[1]=r(4) 偏大,保留 r(3) 作为局部 dot 间隙
+      gap: r(3),
+      paddingTop: space['3'],
+    },
+    /** 'overlay-bottom-right' 模式:absolute 浮在 Carousel 右下角,
+     *  override `justifyContent` → 'flex-end' 让 dot 群靠右。 */
+    dotsWrapOverlay: {
+      position: 'absolute',
+      bottom: space['3'],
+      right: space['5'],
+      flexDirection: 'row',
+      justifyContent: 'flex-end',
+      alignItems: 'center',
+      gap: r(3),
+    },
+    dot: {
+      width: space['1'],
+      height: space['1'],
+      // 4×4 dot 走 pill —— 任意大正数都会被 clamp 成圆,自文档化
+      borderRadius: radius.pill,
+      backgroundColor: c.primary,
+      opacity: 0.32,
+    },
+    /** activeDot —— 12×4 长条,Pagination.Custom 会把 dotStyle 的 height /
+     *  borderRadius 与 activeDotStyle 的 width 一起 interpolate,这里只 override 变化值。 */
+    dotActive: {
+      width: space['5'],
+      opacity: 1,
+    },
+  });

package/src/components/ui/Carousel/types.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** Indicator 位置策略:
+ *  - 'bottom'(默认):指示器独立行,跟 Carousel 下方;容器高度 = height + 16
+ *  - 'overlay-bottom-right':指示器 absolute 浮在 Carousel 右下角,不占额外高度 */
+export type CarouselIndicatorPosition = 'bottom' | 'overlay-bottom-right';
+
+export type CarouselProps<T> = {
+  /** 数组数据 */
+  items: ReadonlyArray<T>;
+  /** 单项渲染 */
+  renderItem: (item: T, index: number) => ReactNode;
+  /** 每张高度(宽度默认 = 屏宽,被 itemWidth 覆盖) */
+  height: number;
+  /** 每张宽度,默认 useWindowDimensions().width。
+   *  若 caller 外层有 marginHorizontal(如 Dashboard banner inset 16),需要传
+   *  `屏宽 - 左右 margin*2`,否则 slide 宽度超过可视区,右侧内容被裁切。 */
+  itemWidth?: number;
+  /** autoPlay 间隔 ms,undefined / 0 不自动 */
+  autoPlay?: number;
+  /** 是否显示底部 dot indicator,默认 true */
+  showIndicator?: boolean;
+  /** indicator 位置策略,默认 'bottom' */
+  indicatorPosition?: CarouselIndicatorPosition;
+  /** 单项点击 */
+  onPressItem?: (item: T, index: number) => void;
+  /** 单项 a11y label 解析器。仅 `onPressItem` 存在时启用 —— Pressable 拿来作
+   *  `accessibilityLabel`(role 自动设 button)。不传则 fallback `第 N 项`。 */
+  getAccessibilityLabel?: (item: T, index: number) => string;
+  /** 外层 View 附加样式 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

package/src/components/ui/Cell/Cell.tsx

@@ -0,0 +1,109 @@
+import React from 'react';
+import { type StyleProp, Text, type TextStyle, View } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { useColors, useThemedStyles } from '../../../theme';
+import { Icon } from '../Icon';
+import { useListVariant } from './context';
+import { Leading } from './Leading';
+import { makeStyles } from './styles';
+import type { CellProps } from './types';
+
+function renderSlot(
+  value: React.ReactNode,
+  textStyle: StyleProp<TextStyle>,
+  numberOfLines: number
+): React.ReactNode {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    return (
+      <Text style={textStyle} numberOfLines={numberOfLines}>
+        {value}
+      </Text>
+    );
+  }
+  return value;
+}
+
+/**
+ * 设置 / 列表行。布局:`leading? · (title / desc) · extra? · arrow?`
+ *
+ * 两种风格(由父 `<List>` 通过 ListVariantContext 决定):
+ * - `grouped`(默认):独立白卡片 + 8px 间距
+ * - `flush`(嵌在 Card 内):紧凑列表,28×28 橙色 icon 盒子,行间 inset hairline 分隔
+ */
+export function Cell({
+  title,
+  titleLines,
+  desc,
+  extra,
+  arrow,
+  leading,
+  onPress,
+  disabled,
+  danger,
+  style,
+  testID,
+  accessibilityLabel,
+  accessibilityHint,
+}: CellProps): React.JSX.Element {
+  const c = useColors();
+  const styles = useThemedStyles(makeStyles);
+  const variant = useListVariant();
+  const flush = variant === 'flush';
+
+  const cellStyle = [
+    styles.cell,
+    flush && styles.cellFlush,
+    flush && desc != null && styles.cellFlushWithDesc,
+    style,
+  ];
+
+  const titleColor = danger ? c.error : undefined;
+  const titleStyle = [
+    flush ? styles.titleFlush : styles.title,
+    titleColor && { color: titleColor },
+  ];
+  const descStyle = flush ? styles.descFlush : styles.desc;
+  const extraStyle = flush ? styles.extraFlush : styles.extra;
+
+  const inner = (
+    <View style={cellStyle} testID={onPress ? undefined : testID}>
+      {leading != null ? <Leading slot={leading} danger={danger} /> : null}
+      <View style={styles.body}>
+        {renderSlot(title, titleStyle, titleLines ?? 1)}
+        {renderSlot(desc, descStyle, 2)}
+      </View>
+      {renderSlot(extra, extraStyle, 1)}
+      {arrow && !danger ? (
+        <Icon
+          name="chevron-right"
+          size={flush ? 18 : 20}
+          color={c.foregroundSubtle}
+          style={flush ? styles.chevronFlush : undefined}
+        />
+      ) : null}
+    </View>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={onPress}
+        disabled={disabled}
+        accessibilityRole="button"
+        accessibilityLabel={
+          accessibilityLabel ?? (typeof title === 'string' ? title : undefined)
+        }
+        accessibilityHint={accessibilityHint}
+        accessibilityState={disabled ? { disabled: true } : undefined}
+        testID={testID}
+        style={({ pressed }) => [
+          { opacity: disabled ? 0.5 : pressed ? 0.7 : 1 },
+        ]}
+      >
+        {inner}
+      </Pressable>
+    );
+  }
+  return inner;
+}

package/src/components/ui/Cell/Leading.tsx

@@ -0,0 +1,59 @@
+import { type ReactNode } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { r, useColors } from '../../../theme';
+import { Icon, type IconName } from '../Icon';
+import { useListVariant } from './context';
+
+const FLUSH_BOX_SIZE = r(28);
+const FLUSH_BOX_RADIUS = r(7);
+
+const sharedStyles = StyleSheet.create({
+  flushBox: {
+    width: FLUSH_BOX_SIZE,
+    height: FLUSH_BOX_SIZE,
+    borderRadius: FLUSH_BOX_RADIUS,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});
+
+export function Leading({
+  slot,
+  danger,
+}: {
+  slot: IconName | ReactNode;
+  danger?: boolean;
+}) {
+  const c = useColors();
+  const variant = useListVariant();
+
+  if (typeof slot === 'string') {
+    // grouped 模式:裸 icon 22px;flush 模式:28×28 圆角盒子,danger 时切 error-container
+    if (variant === 'flush') {
+      return (
+        <View
+          style={[
+            sharedStyles.flushBox,
+            {
+              backgroundColor: danger ? c.errorContainer : c.primaryContainer,
+            },
+          ]}
+        >
+          <Icon
+            name={slot as IconName}
+            size={16}
+            color={danger ? c.error : c.primary}
+          />
+        </View>
+      );
+    }
+    return (
+      <Icon
+        name={slot as IconName}
+        size={22}
+        color={danger ? c.error : c.foregroundMuted}
+      />
+    );
+  }
+  return <View>{slot}</View>;
+}

package/src/components/ui/Cell/List.tsx

@@ -0,0 +1,46 @@
+import React from 'react';
+import { View } from 'react-native';
+import { useThemedStyles } from '../../../theme';
+import { ListVariantContext } from './context';
+import { makeStyles } from './styles';
+import type { ListProps } from './types';
+
+/**
+ * Cell 的分组容器。
+ *
+ * - 默认 `grouped` = 灰底排列白卡片,间距 8px
+ * - `flush=true` = 嵌在外层 Card 内,紧凑列表;`divider="full"` 铺满全宽 hairline / `"none"` 无分隔线
+ */
+export function List({
+  children,
+  flush,
+  divider = 'full',
+  style,
+  testID,
+}: ListProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  if (flush) {
+    const items = React.Children.toArray(children).filter(Boolean);
+    return (
+      <ListVariantContext.Provider value="flush">
+        <View style={[styles.listFlush, style]} testID={testID}>
+          {items.map((child, i) => (
+            <React.Fragment key={i}>
+              {i > 0 && divider === 'full' ? (
+                <View style={styles.separator} />
+              ) : null}
+              {child}
+            </React.Fragment>
+          ))}
+        </View>
+      </ListVariantContext.Provider>
+    );
+  }
+  return (
+    <ListVariantContext.Provider value="grouped">
+      <View style={[styles.list, styles.listGrouped, style]} testID={testID}>
+        {children}
+      </View>
+    </ListVariantContext.Provider>
+  );
+}

package/src/components/ui/Cell/context.ts

@@ -0,0 +1,10 @@
+import { createContext, useContext } from 'react';
+
+/** List → Cell 间的样式风格通道。
+ *  - 'grouped' = 默认,每个 Cell 独立白卡片 + 8px 间距,无 cell 间分隔线
+ *  - 'flush' = 紧凑列表,28×28 圆角 7 icon 盒子,Cell 之间 hairline 分隔线 */
+export type ListVariant = 'grouped' | 'flush';
+
+export const ListVariantContext = createContext<ListVariant>('grouped');
+
+export const useListVariant = (): ListVariant => useContext(ListVariantContext);

package/src/components/ui/Cell/index.ts

@@ -0,0 +1,3 @@
+export { Cell } from './Cell';
+export { List } from './List';
+export type { CellProps, ListProps } from './types';

package/src/components/ui/Cell/styles.ts

@@ -0,0 +1,91 @@
+import { StyleSheet } from 'react-native';
+import {
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
+
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    cell: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: space[5],
+      paddingHorizontal: space[6],
+      paddingVertical: space[6],
+      minHeight: r(56),
+      backgroundColor: c.surface,
+      borderRadius: radius.lg,
+    },
+    cellFlush: {
+      backgroundColor: 'transparent',
+      borderRadius: 0,
+      gap: space[4],
+      paddingHorizontal: r(11),
+      paddingVertical: r(11),
+      minHeight: 0,
+    },
+    cellFlushWithDesc: {
+      paddingVertical: r(9),
+    },
+    body: {
+      flex: 1,
+      minWidth: 0,
+      gap: r(2),
+    },
+    title: {
+      fontSize: t.body,
+      fontWeight: fw.medium,
+      color: c.foreground,
+      lineHeight: t.body * 1.3,
+    },
+    titleFlush: {
+      fontSize: r(13),
+      fontWeight: fw.medium,
+      letterSpacing: -0.1,
+      lineHeight: r(13) * 1.3,
+      color: c.foreground,
+    },
+    desc: {
+      fontSize: t.xs,
+      color: c.foregroundSubtle,
+      lineHeight: t.xs * 1.4,
+    },
+    descFlush: {
+      fontSize: r(11),
+      color: c.foregroundMuted,
+      opacity: 0.55,
+      marginTop: r(1),
+    },
+    extra: {
+      fontSize: t.xs,
+      color: c.foregroundSubtle,
+    },
+    extraFlush: {
+      fontSize: r(11),
+      color: c.foregroundMuted,
+      opacity: 0.55,
+    },
+    chevronFlush: {
+      opacity: 0.35,
+    },
+    /** flush 行间分隔线 —— hairline + outline,铺满 cell 全宽 */
+    separator: {
+      height: StyleSheet.hairlineWidth,
+      backgroundColor: c.outline,
+    },
+    list: {
+      gap: space[3],
+    },
+    listGrouped: {
+      backgroundColor: c.background,
+      padding: space[3],
+      borderRadius: radius.xl,
+    },
+    listFlush: {
+      backgroundColor: 'transparent',
+    },
+  });

package/src/components/ui/Cell/types.ts

@@ -0,0 +1,53 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../Icon';
+
+export type CellProps = {
+  /** 标题（必填）；string 自动套 Text + numberOfLines=titleLines，传 ReactNode 完全自定义 */
+  title: ReactNode;
+  /** title 是 string 时的 numberOfLines（默认 1）。多行场景如新闻列表标题传 2。 */
+  titleLines?: number;
+  /** 副标题；string 自动 numberOfLines=2，传 ReactNode 完全自定义 */
+  desc?: ReactNode;
+  /** 右侧 slot —— 字符串自动套 Text；传 ReactNode 放 Switch / Stepper / Tag 等控件 */
+  extra?: ReactNode;
+  /** 显示右侧 chevron-right 图标，常配合 onPress 表示「可进入下一级」 */
+  arrow?: boolean;
+  /** 前置 slot —— IconName 自动渲染 24×24 图标；传 ReactNode 放 Avatar / 自定义图形 */
+  leading?: IconName | ReactNode;
+  /** 点击回调 —— 不传则 cell 不可点（纯展示） */
+  onPress?: () => void;
+  /**
+   * 显式禁用：仅对带 onPress 的 cell 有效。
+   * disabled=true 时 onPress 不触发 + 整体半透明 + a11y disabled。
+   */
+  disabled?: boolean;
+  /** 危险态:icon 盒子 + 标题用 error 红色,且不渲染 arrow(常用于退出登录 / 删除等)。 */
+  danger?: boolean;
+  /** 额外样式覆盖(合并到 cell 容器的 style 数组) */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+  /** 显式 SR 朗读文案,覆盖 Cell 默认从 string title 推断的 fallback。
+   *  title 是 ReactNode(自定义渲染)时尤其需要,否则 SR 用户听不到任何内容。 */
+  accessibilityLabel?: string;
+  /** SR 朗读 hint —— 说明 tap 后行为(参 CLAUDE.md a11y 章节,短 ≤8 字)。
+   *  常用:"查看详情" / "打开应用" 等;onPress 缺省时此 prop 无意义。 */
+  accessibilityHint?: string;
+};
+
+export type ListProps = {
+  /** 一组 Cell */
+  children: ReactNode;
+  /**
+   * `flush=true` 时不画灰色容器,行直接放在透明背景上。
+   * 用于:嵌套在 Card 内 / 第一屏 hero 区下方等已有底色的场景。
+   */
+  flush?: boolean;
+  /** flush 模式下行间分隔线样式,默认 `'full'`(铺满全宽 hairline) / `'none'` 不画 */
+  divider?: 'full' | 'none';
+  /** 额外样式覆盖 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+};