@unif/react-native-design 0.1.0

package/src/components/ui/EntryCard/EntryCard.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { Icon } from '../Icon';
+import { useColors, useThemedStyles } from '../../../theme';
+import { makeStyles } from './styles';
+import type { EntryCardProps } from './types';
+
+/** 入口横向小卡 —— 独立 surface 小卡视觉,不依赖 List 容器,
+ *  无 arrow / extra,纯入口语义,放在 grid 双列里靠 caller `style={{flex:1}}` 撑等宽。 */
+export function EntryCard({
+  icon,
+  title,
+  sub,
+  onPress,
+  style,
+  testID,
+}: EntryCardProps): React.JSX.Element {
+  const c = useColors();
+  const styles = useThemedStyles(makeStyles);
+
+  const content = (
+    <>
+      <View style={styles.iconTile}>
+        <Icon name={icon} size={16} color={c.foregroundMuted} />
+      </View>
+      <View style={styles.body}>
+        <Text style={styles.title} numberOfLines={1}>
+          {title}
+        </Text>
+        {sub ? (
+          <Text style={styles.sub} numberOfLines={1}>
+            {sub}
+          </Text>
+        ) : null}
+      </View>
+    </>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={title}
+        testID={testID}
+        style={({ pressed }) => [styles.card, pressed && styles.pressed, style]}
+      >
+        {content}
+      </Pressable>
+    );
+  }
+  return (
+    <View style={[styles.card, style]} testID={testID}>
+      {content}
+    </View>
+  );
+}

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

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

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

@@ -0,0 +1,44 @@
+import { StyleSheet } from 'react-native';
+import { fw, icon, r, radius, space, type ColorTokens } from '../../../theme';
+
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    card: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: space[4],
+      backgroundColor: c.surface,
+      borderRadius: radius['2xl'],
+      paddingVertical: space[5],
+      paddingHorizontal: space[6],
+    },
+    iconTile: {
+      width: icon.lg,
+      height: icon.lg,
+      // 9pt 介于 radius.md(8) / radius.lg(10) 之间,匹配 30×30 tile 的视觉圆度
+      borderRadius: r(9),
+      backgroundColor: c.surfaceContainer,
+      alignItems: 'center',
+      justifyContent: 'center',
+      flexShrink: 0,
+    },
+    body: {
+      flex: 1,
+      minWidth: 0,
+      gap: space.px,
+    },
+    title: {
+      // 13.5pt —— 介于 type.xs(13) / type.sm(14) 之间的设计稿专定字号
+      fontSize: r(13) + 0.5,
+      fontWeight: fw.medium,
+      letterSpacing: -0.2,
+      color: c.foreground,
+    },
+    sub: {
+      fontSize: r(11),
+      color: c.foregroundMuted,
+    },
+    pressed: {
+      opacity: 0.7,
+    },
+  });

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

@@ -0,0 +1,17 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../Icon';
+
+export type EntryCardProps = {
+  /** 左侧 icon tile 内的图标名 */
+  icon: IconName;
+  /** 主标题(13.5px medium) */
+  title: string;
+  /** 副标题(11px muted),省略不渲染该行 */
+  sub?: string;
+  /** 点击回调,未传不挂 Pressable */
+  onPress?: () => void;
+  /** 外层附加样式 —— 常用于 grid 列设 `flex: 1` */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

package/src/components/ui/Form/Form.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { View } from 'react-native';
+import { useThemedStyles } from '../../../theme';
+import { makeStyles } from './styles';
+import type { FormProps } from './types';
+
+/**
+ * 表单根容器 —— 纵向堆叠多个 FormGroup。
+ */
+export function Form({ children, testID }: FormProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  return (
+    <View style={styles.form} testID={testID}>
+      {children}
+    </View>
+  );
+}

package/src/components/ui/Form/FormGroup.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { useThemedStyles } from '../../../theme';
+import { makeStyles } from './styles';
+import type { FormGroupProps } from './types';
+
+/**
+ * 白卡片上的分组：分组标题 + 一组行。
+ * 组内行之间用 1px 细线分隔（表单是「不用 gap」规则的例外）。
+ *
+ * **业务约定：** 动态列表（运行时增删 FormRow）必须给每个 child 传稳定 `key` prop。
+ * 不传时 fallback 到 `__row-${i}` —— 仅适用于**静态**列表，动态列表会导致 state 漂移。
+ */
+export function FormGroup({
+  label,
+  children,
+  testID,
+}: FormGroupProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  const arr = React.Children.toArray(children);
+  return (
+    <View style={styles.group} testID={testID}>
+      {label ? (
+        <Text style={styles.groupLabel} numberOfLines={1}>
+          {label}
+        </Text>
+      ) : null}
+      <View style={styles.groupBody}>
+        {arr.map((child, i) => {
+          const childKey =
+            React.isValidElement(child) && child.key != null
+              ? child.key
+              : `__row-${i}`;
+          return (
+            <View key={childKey} style={i > 0 ? styles.divider : null}>
+              {child}
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}

package/src/components/ui/Form/FormRow.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { useThemedStyles } from '../../../theme';
+import { makeStyles } from './styles';
+import type { FormRowProps } from './types';
+
+/**
+ * 带 label 的单行表单项。布局：左 label · 右控件。最小高度 48。
+ */
+export function FormRow({
+  label,
+  children,
+  required,
+  error,
+  testID,
+}: FormRowProps): React.JSX.Element {
+  const styles = useThemedStyles(makeStyles);
+  return (
+    <View style={styles.row} testID={testID}>
+      <View style={styles.rowMain}>
+        <Text style={styles.rowLabel} numberOfLines={1}>
+          {label}
+          {required ? <Text style={styles.required}> *</Text> : null}
+        </Text>
+        <View style={styles.rowControl}>{children}</View>
+      </View>
+      {error ? <Text style={styles.errorText}>{error}</Text> : null}
+    </View>
+  );
+}

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

@@ -0,0 +1,4 @@
+export { Form } from './Form';
+export { FormGroup } from './FormGroup';
+export { FormRow } from './FormRow';
+export type { FormProps, FormGroupProps, FormRowProps } from './types';

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

@@ -0,0 +1,64 @@
+import { StyleSheet } from 'react-native';
+import {
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
+
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    form: {
+      gap: space[7],
+    },
+    group: {
+      gap: space[3],
+    },
+    groupLabel: {
+      fontSize: t.xs,
+      fontWeight: fw.semi,
+      color: c.foregroundSubtle,
+      textTransform: 'uppercase',
+      letterSpacing: 1,
+      paddingHorizontal: space[1],
+    },
+    groupBody: {
+      backgroundColor: c.surface,
+      borderRadius: radius.lg,
+      overflow: 'hidden',
+    },
+    divider: {
+      borderTopWidth: StyleSheet.hairlineWidth,
+      borderTopColor: c.outline,
+    },
+    row: {
+      paddingHorizontal: space[7],
+      paddingVertical: space[5],
+      minHeight: r(48),
+      justifyContent: 'center',
+    },
+    rowMain: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      gap: space[5],
+    },
+    rowLabel: {
+      fontSize: t.sm,
+      fontWeight: fw.medium,
+      color: c.foreground,
+    },
+    required: {
+      color: c.error,
+    },
+    rowControl: {
+      flex: 1,
+      alignItems: 'flex-end',
+    },
+    errorText: {
+      fontSize: t.micro,
+      color: c.error,
+      marginTop: space[1],
+    },
+  });

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

@@ -0,0 +1,30 @@
+import type { ReactNode } from 'react';
+
+export type FormProps = {
+  /** Form 内部内容，通常是若干个 FormGroup / FormRow */
+  children: ReactNode;
+  /** E2E / 测试定位 */
+  testID?: string;
+};
+
+export type FormGroupProps = {
+  /** 分组标题（uppercase 小标签风格） */
+  label?: string;
+  /** 该分组下若干个 FormRow */
+  children: ReactNode;
+  /** E2E / 测试定位 */
+  testID?: string;
+};
+
+export type FormRowProps = {
+  /** 字段标题 */
+  label: string;
+  /** 字段控件（Input / Select / etc） */
+  children: ReactNode;
+  /** 必填标记，渲染右上红色星号 */
+  required?: boolean;
+  /** 错误信息，渲染在控件下方 */
+  error?: string;
+  /** E2E / 测试定位 */
+  testID?: string;
+};

package/src/components/ui/Grid/Grid.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { childTestID } from '../../../utils/testID';
+import { Icon } from '../Icon';
+import { colWidth, makeStyles } from './styles';
+import type { GridProps } from './types';
+
+const log = createLogger('Grid');
+
+/**
+ * 图标入口宫格 —— 首页 / 分类落地页。1..6 列。
+ * 每格：图标 + 小标签，纵向居中。
+ *
+ * 性能：列宽走 StyleSheet 预生成规则（colWidth），避免每个 cell 创建内联对象。
+ */
+export function Grid({
+  items,
+  columns = 4,
+  onPress,
+  card = true,
+  testID,
+}: GridProps): React.JSX.Element {
+  const c = useColors();
+  const styles = useThemedStyles(makeStyles);
+  if (![1, 2, 3, 4, 5, 6].includes(columns)) {
+    log.warn(`columns 仅支持 1..6，传入 ${columns}，已 fallback 为 4 列`);
+  }
+  const cellWidth = colWidth(columns);
+  return (
+    <View style={[styles.wrap, card && styles.card]} testID={testID}>
+      <View style={styles.inner}>
+        {items.map((item) => {
+          const itemTestID = childTestID(testID, item.id, item.testID);
+          return (
+            <View key={item.id} style={cellWidth}>
+              <Pressable
+                onPress={() => onPress?.(item)}
+                accessibilityRole="button"
+                accessibilityLabel={item.label}
+                testID={itemTestID}
+                style={({ pressed }) => [
+                  styles.cell,
+                  { opacity: pressed ? 0.7 : 1 },
+                ]}
+              >
+                <View>
+                  {/* 28pt 介于 icon.md(26) / icon.lg(30) 之间的设计稿专定字号 */}
+                  <Icon name={item.icon} size={28} color={c.foregroundMuted} />
+                  {item.badge != null ? (
+                    <View style={styles.badge}>
+                      <Text style={styles.badgeText}>{item.badge}</Text>
+                    </View>
+                  ) : null}
+                </View>
+                <Text style={styles.label} numberOfLines={1}>
+                  {item.label}
+                </Text>
+              </Pressable>
+            </View>
+          );
+        })}
+      </View>
+    </View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Grid } from './Grid';
+export type { GridItem, GridProps } from './types';

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

@@ -0,0 +1,88 @@
+import { StyleSheet } from 'react-native';
+import {
+  fw,
+  r,
+  radius,
+  space,
+  type as t,
+  type ColorTokens,
+} from '../../../theme';
+
+/**
+ * 预生成 1..6 列的宽度规则，避免 render 时创建 `{ width: pct }` 内联对象
+ * 让 Grid 在长列表 / 多 cell 场景下复用 StyleSheet 缓存。
+ */
+const COLUMN_WIDTHS = StyleSheet.create({
+  col1: { width: '100%' },
+  col2: { width: '50%' },
+  col3: { width: '33.333%' },
+  col4: { width: '25%' },
+  col5: { width: '20%' },
+  col6: { width: '16.666%' },
+});
+
+export const colWidth = (columns: number) => {
+  switch (columns) {
+    case 1:
+      return COLUMN_WIDTHS.col1;
+    case 2:
+      return COLUMN_WIDTHS.col2;
+    case 3:
+      return COLUMN_WIDTHS.col3;
+    case 5:
+      return COLUMN_WIDTHS.col5;
+    case 6:
+      return COLUMN_WIDTHS.col6;
+    case 4:
+    default:
+      return COLUMN_WIDTHS.col4;
+  }
+};
+
+export const makeStyles = (c: ColorTokens) =>
+  StyleSheet.create({
+    wrap: {
+      width: '100%',
+    },
+    card: {
+      backgroundColor: c.surface,
+      borderRadius: radius.xl,
+      paddingVertical: space[5],
+      paddingHorizontal: space[3],
+      borderWidth: 1,
+      borderColor: c.outline,
+    },
+    inner: {
+      flexDirection: 'row',
+      flexWrap: 'wrap',
+    },
+    cell: {
+      paddingVertical: space[5],
+      alignItems: 'center',
+      justifyContent: 'center',
+      gap: space[2],
+    },
+    label: {
+      fontSize: t.xxs,
+      fontWeight: fw.medium,
+      color: c.foreground,
+    },
+    badge: {
+      position: 'absolute',
+      top: r(-6),
+      right: r(-10),
+      minWidth: r(16),
+      height: r(16),
+      borderRadius: radius.md,
+      backgroundColor: c.error,
+      paddingHorizontal: space[1],
+      alignItems: 'center',
+      justifyContent: 'center',
+    },
+    badgeText: {
+      color: c.onError,
+      fontSize: t.nano,
+      fontWeight: fw.bold,
+      lineHeight: 12,
+    },
+  });

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

@@ -0,0 +1,25 @@
+import type { IconName } from '../Icon';
+
+export type GridItem = {
+  id: string;
+  icon: IconName;
+  label: string;
+  /** 图标右上角的数字角标（用 string 才能写 '99+'） */
+  badge?: number | string;
+  /** 单 cell 测试定位（不传则自动用 `${gridTestID}-${id}`） */
+  testID?: string;
+};
+
+export type GridProps = {
+  items: GridItem[];
+  /**
+   * 列数 1..6；默认 4。
+   * ⚠️ 类型外的值（如 `7`）会**静默**回退到 4 列 — 业务应在传入前自行校验。
+   */
+  columns?: 1 | 2 | 3 | 4 | 5 | 6;
+  onPress?: (item: GridItem) => void;
+  /** 是否套白色卡片；传 false 则背景透明 */
+  card?: boolean;
+  /** 容器 testID；item testID 会自动派生为 `${testID}-${item.id}` */
+  testID?: string;
+};

package/src/components/ui/Icon/Icon.tsx

@@ -0,0 +1,82 @@
+import React from 'react';
+import { View } from 'react-native';
+import Svg, { Circle, Path, Rect } from 'react-native-svg';
+import { ICONS, type IconDef } from '../../../icons';
+import { useColors } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import type { IconProps } from './types';
+
+const log = createLogger('Icon');
+
+export function Icon({
+  name,
+  size = 18,
+  color,
+  strokeWidth,
+  style,
+  testID,
+}: IconProps): React.JSX.Element {
+  const c = useColors();
+  const stroke = color ?? c.foregroundMuted;
+  const def: IconDef | undefined = ICONS[name];
+  if (!def) {
+    log.warn(`unknown icon: ${name}`);
+    return (
+      <View
+        style={[{ width: size, height: size }, style]}
+        testID={testID}
+        accessibilityElementsHidden
+        importantForAccessibility="no-hide-descendants"
+      />
+    );
+  }
+  const sw = strokeWidth ?? def.strokeWidth;
+
+  return (
+    <View
+      style={style}
+      testID={testID}
+      accessibilityElementsHidden
+      importantForAccessibility="no-hide-descendants"
+    >
+      <Svg
+        width={size}
+        height={size}
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke={stroke}
+        strokeWidth={sw}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        {def.elements.map((el, i) => {
+          const fill =
+            el.fill === 'currentColor' ? stroke : (el.fill ?? 'none');
+          if (el.kind === 'path') {
+            return <Path key={i} d={el.d} fill={fill} />;
+          }
+          if (el.kind === 'circle') {
+            return (
+              <Circle key={i} cx={el.cx} cy={el.cy} r={el.r} fill={fill} />
+            );
+          }
+          if (el.kind === 'rect') {
+            return (
+              <Rect
+                key={i}
+                x={el.x}
+                y={el.y}
+                width={el.width}
+                height={el.height}
+                rx={el.rx}
+                ry={el.ry}
+                fill={fill}
+              />
+            );
+          }
+          return null;
+        })}
+      </Svg>
+    </View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Icon } from './Icon';
+export type { IconName, IconProps } from './types';

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

@@ -0,0 +1,15 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../../icons';
+
+export type { IconName };
+
+export type IconProps = {
+  name: IconName;
+  size?: number;
+  color?: string;
+  /** 覆盖描边宽度（默认按每个图标自带值，多数 1.75，少数 2） */
+  strokeWidth?: number;
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位（挂在外层 View） */
+  testID?: string;
+};

package/src/components/ui/IconButton/IconButton.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { ButtonBase } from '../Button/ButtonBase';
+import { Icon } from '../Icon';
+import type { IconButtonProps } from './types';
+
+/**
+ * Icon-only 按钮 —— 与 Button 共享 ButtonBase chrome。
+ *
+ * `square=true` 触发 ButtonBase 方形布局(width=height=sizing.h)。
+ * Icon 大小由 `sizing.fs + 4` 决定 —— 无文本平衡,稍大于 Button 内 icon(`fs + 2`)。
+ *
+ * `accessibilityLabel` TypeScript 强制必填 —— icon-only 无文本提示语义,
+ * SR 必须靠 a11y label 朗读。
+ */
+export function IconButton({
+  icon,
+  onPress,
+  size = 'md',
+  variant = 'ghost',
+  color,
+  disabled,
+  accessibilityLabel,
+  accessibilityHint,
+  style,
+  testID,
+}: IconButtonProps): React.JSX.Element {
+  return (
+    <ButtonBase
+      square
+      onPress={onPress}
+      size={size}
+      variant={variant}
+      disabled={disabled}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityHint={accessibilityHint}
+      style={style}
+      testID={testID}
+    >
+      {({ sizing, palette }) => (
+        <Icon name={icon} size={sizing.fs + 4} color={color ?? palette.fg} />
+      )}
+    </ButtonBase>
+  );
+}

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

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

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

@@ -0,0 +1,28 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../Icon';
+import type { ButtonSize, ButtonVariant } from '../Button/types';
+
+export type IconButtonProps = {
+  /** 图标名 */
+  icon: IconName;
+  /** 点击;disabled 时不触发 */
+  onPress?: () => void;
+  /** 尺寸,默认 'md'(28 / 36 / 44 方形) */
+  size?: ButtonSize;
+  /** 视觉变体,默认 'ghost'(透明底,适合 header right-tray 场景) */
+  variant?: ButtonVariant;
+  /** Icon 颜色 override —— 不传走 variant.palette.fg(品牌一致默认);
+   *  caller 显式控制 icon 色场景(eg NavBar 内部按 variant 推导出 foreground /
+   *  onPrimary)。仅影响 icon 色,bg/border 仍由 variant palette 决定。 */
+  color?: string;
+  /** 整体禁用:opacity 0.5 + 不响应 */
+  disabled?: boolean;
+  /** **必填** — 无文本提示语义,SR 需要 */
+  accessibilityLabel: string;
+  /** SR 朗读 label 后的行为说明 hint。仅在"行为不显然"时加。 */
+  accessibilityHint?: string;
+  /** 额外样式 */
+  style?: StyleProp<ViewStyle>;
+  /** E2E / 测试定位 */
+  testID?: string;
+};