zkit-ui 1.0.0

package/src/ui/Text/README.md

@@ -0,0 +1,157 @@
+# Text
+
+`Text` 是 zkit 的统一文字原语。它集中处理排版 token、主题色、字体缩放、截断和跨端字重差异，让业务和公共组件都走同一套文字规则。
+
+## 设计取舍
+
+- `Text` 是无状态组件，没有受控/非受控语义。
+- `variant` 表达排版语义，`tone` 表达颜色意图，`style` 只作为最终 escape hatch。
+- 内置字号和行高按设计像素声明，组件内部统一通过 `wp(...)` 计算。
+- 默认使用 `getMaxFontSizeMultiplier()` 限制字体缩放上限，单次可用 `maxFontSizeMultiplier` 覆盖。
+- Android 默认关闭 `includeFontPadding`，用明确 lineHeight 保证 iOS / Android / Web 视觉高度更一致。
+- `color` 支持主题 token、语义色 token 和原生可解析颜色；无效颜色会回落到 `tone`。
+- 屏幕宽度变化时会重新计算排版尺寸，横竖屏和分屏场景不会卡在初始化尺寸。
+
+## 基础用法
+
+```tsx
+import { Text } from 'zkit-ui';
+
+export function Demo() {
+  return <Text>默认正文</Text>;
+}
+```
+
+默认等价于：
+
+- `variant="body"`
+- `tone="default"`
+- `size="md"`
+- `weight="regular"`
+- `maxFontSizeMultiplier={getMaxFontSizeMultiplier()}`
+
+## 排版语义
+
+```tsx
+import { Text } from 'zkit-ui';
+
+export function Demo() {
+  return (
+    <>
+      <Text variant="display">页面主标题</Text>
+      <Text variant="heading">分区标题</Text>
+      <Text variant="title">列表标题</Text>
+      <Text variant="body">正文内容</Text>
+      <Text variant="label">表单标签</Text>
+      <Text variant="caption" tone="muted">
+        辅助说明
+      </Text>
+      <Text variant="code">const ready = true;</Text>
+    </>
+  );
+}
+```
+
+`variant` 只决定默认 `size / weight / fontFamily`，显式传入 `size`、`weight` 或 `style` 时会覆盖对应值。
+
+## 尺寸
+
+```tsx
+<>
+  <Text size="2xs">2xs</Text>
+  <Text size="xs">xs</Text>
+  <Text size="sm">sm</Text>
+  <Text size="md">md</Text>
+  <Text size="lg">lg</Text>
+  <Text size="xl">xl</Text>
+  <Text size="2xl">2xl</Text>
+  <Text size="3xl">3xl</Text>
+  <Text size="4xl">4xl</Text>
+  <Text size={18} lineHeight={26}>
+    自定义设计尺寸
+  </Text>
+</>
+```
+
+内置尺寸：
+
+| size | fontSize | lineHeight |
+| --- | ---: | ---: |
+| `2xs` | `wp(11)` | `wp(14)` |
+| `xs` | `wp(12)` | `wp(16)` |
+| `sm` | `wp(13)` | `wp(18)` |
+| `md` | `wp(15)` | `wp(21)` |
+| `lg` | `wp(17)` | `wp(24)` |
+| `xl` | `wp(20)` | `wp(28)` |
+| `2xl` | `wp(24)` | `wp(32)` |
+| `3xl` | `wp(30)` | `wp(38)` |
+| `4xl` | `wp(36)` | `wp(44)` |
+
+传入数字 `size` 或 `lineHeight` 时，数字代表未缩放的设计像素，组件内部会统一转换。
+
+## 颜色
+
+```tsx
+<>
+  <Text tone="default">默认文字</Text>
+  <Text tone="muted">弱化文字</Text>
+  <Text tone="primary">强调文字</Text>
+  <Text tone="success">成功状态</Text>
+  <Text tone="warning">警示状态</Text>
+  <Text tone="danger">危险状态</Text>
+  <Text tone="disabled">禁用说明</Text>
+  <Text color="onPrimary">主题 token</Text>
+  <Text color="#DC2626">一次性颜色</Text>
+</>
+```
+
+常用 `tone`：
+
+- `default` / `neutral`：`theme.colors.onSurface`
+- `muted`：`theme.colors.muted`
+- `subtle` / `disabled`：`theme.colors.disabled`
+- `primary`：`theme.colors.primary`
+- `success` / `warning` / `danger` / `info`：内置语义状态色
+- `inverse` / `onPrimary`：`theme.colors.onPrimary`
+- `onSecondary`：`theme.colors.onSecondary`
+- `inherit`：不设置颜色，用于嵌套文字继承父级颜色
+
+```tsx
+<Text tone="primary">
+  已选择 <Text tone="inherit" weight="bold">3</Text> 项
+</Text>
+```
+
+## 截断、字重和数字
+
+```tsx
+<>
+  <Text truncate>单行省略</Text>
+  <Text truncate={2}>最多两行</Text>
+  <Text weight="semibold">语义字重</Text>
+  <Text weight="850">自定义字重会归一化到 100-900</Text>
+  <Text tabularNumbers>12:08 / 98%</Text>
+</>
+```
+
+- `truncate` 是 `numberOfLines` 和默认 `ellipsizeMode="tail"` 的语义化快捷方式。
+- `weight` 支持 `regular / medium / semibold / bold / heavy / black`，也支持 React Native 原生 `fontWeight`。
+- Web 常见字重名会被映射到稳定数字权重；Android API 28 以下会降级到 `normal / bold`。
+- `tabularNumbers` 用于计时器、金额、百分比等需要数字等宽的场景。
+
+## 原生能力
+
+`Text` 继承 React Native `Text` 的原生能力，包括：
+
+- `numberOfLines`
+- `ellipsizeMode`
+- `allowFontScaling`
+- `maxFontSizeMultiplier`
+- `selectable`
+- `onPress`
+- `onLongPress`
+- `accessibilityRole`
+- `accessibilityLabel`
+- `testID`
+
+公共组件内部应优先使用 `variant / tone / size / weight / truncate`。只有确实需要局部覆盖布局、颜色或字体细节时再使用 `style`。

package/src/ui/Text/index.tsx

@@ -0,0 +1,450 @@
+import * as React from 'react';
+import {
+  Platform,
+  StyleSheet,
+  Text as RNText,
+  type AccessibilityState,
+  type StyleProp,
+  type TextProps as RNTextProps,
+  type TextStyle,
+  processColor,
+  useWindowDimensions,
+} from 'react-native';
+import { getMaxFontSizeMultiplier, wp } from 'zkit-tools';
+import type { Theme } from '../../theme/types';
+import { useTheme } from '../../theme/useTheme';
+
+export type TextVariant = 'body' | 'label' | 'caption' | 'title' | 'heading' | 'display' | 'code';
+export type TextSize = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl';
+export type TextSizeValue = TextSize | number;
+export type TextTone =
+  | 'default'
+  | 'neutral'
+  | 'muted'
+  | 'subtle'
+  | 'primary'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info'
+  | 'disabled'
+  | 'inverse'
+  | 'onPrimary'
+  | 'onSecondary'
+  | 'inherit';
+export type TextWeight =
+  | 'regular'
+  | 'medium'
+  | 'semibold'
+  | 'bold'
+  | 'heavy'
+  | 'black'
+  | NonNullable<TextStyle['fontWeight']>;
+export type TextTruncate = boolean | number;
+
+type NativeTextProps = Omit<RNTextProps, 'style' | 'disabled' | 'numberOfLines' | 'ellipsizeMode'>;
+
+export type TextRef = React.ComponentRef<typeof RNText>;
+
+export interface TextProps extends NativeTextProps {
+  /**
+   * Semantic typography preset. Prefer this over raw font styles.
+   */
+  variant?: TextVariant;
+  /**
+   * Named type scale token, or an unscaled design pixel size that will be resolved through wp(...).
+   */
+  size?: TextSizeValue;
+  /**
+   * Optional line height in design pixels. Style still wins as the final escape hatch.
+   */
+  lineHeight?: number;
+  weight?: TextWeight;
+  tone?: TextTone;
+  /**
+   * Theme color token, semantic token, or processable native color.
+   */
+  color?: string;
+  align?: TextStyle['textAlign'];
+  transform?: TextStyle['textTransform'];
+  truncate?: TextTruncate;
+  tabularNumbers?: boolean;
+  disabled?: boolean;
+  numberOfLines?: RNTextProps['numberOfLines'];
+  ellipsizeMode?: RNTextProps['ellipsizeMode'];
+  style?: StyleProp<TextStyle>;
+}
+
+type TypographyToken = {
+  fontSize: number;
+  lineHeight: number;
+};
+
+type VariantToken = {
+  size: TextSize;
+  weight: TextWeight;
+  fontFamily?: TextStyle['fontFamily'];
+};
+
+const SEMANTIC_COLORS = {
+  danger: '#DC2626',
+  error: '#DC2626',
+  info: '#2563EB',
+  success: '#16A34A',
+  warn: '#D97706',
+  warning: '#D97706',
+} as const;
+
+const SIZE_TOKENS = {
+  '2xs': { fontSize: 11, lineHeight: 14 },
+  xs: { fontSize: 12, lineHeight: 16 },
+  sm: { fontSize: 13, lineHeight: 18 },
+  md: { fontSize: 15, lineHeight: 21 },
+  lg: { fontSize: 17, lineHeight: 24 },
+  xl: { fontSize: 20, lineHeight: 28 },
+  '2xl': { fontSize: 24, lineHeight: 32 },
+  '3xl': { fontSize: 30, lineHeight: 38 },
+  '4xl': { fontSize: 36, lineHeight: 44 },
+} as const satisfies Record<TextSize, TypographyToken>;
+
+const MONOSPACE_FONT_FAMILY = Platform.select({
+  android: 'monospace',
+  ios: 'Menlo',
+  web: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace',
+  default: 'monospace',
+});
+
+const VARIANT_TOKENS = {
+  body: {
+    size: 'md',
+    weight: 'regular',
+  },
+  label: {
+    size: 'sm',
+    weight: 'medium',
+  },
+  caption: {
+    size: 'xs',
+    weight: 'regular',
+  },
+  title: {
+    size: 'lg',
+    weight: 'semibold',
+  },
+  heading: {
+    size: '2xl',
+    weight: 'bold',
+  },
+  display: {
+    size: '3xl',
+    weight: 'bold',
+  },
+  code: {
+    size: 'sm',
+    weight: 'regular',
+    fontFamily: MONOSPACE_FONT_FAMILY,
+  },
+} as const satisfies Record<TextVariant, VariantToken>;
+
+const WEB_NAMED_WEIGHT_MAP: Record<string, number> = {
+  black: 900,
+  bold: 700,
+  book: 400,
+  demibold: 600,
+  extrabold: 800,
+  extralight: 200,
+  hairline: 100,
+  heavy: 900,
+  light: 300,
+  medium: 500,
+  normal: 400,
+  regular: 400,
+  semibold: 600,
+  thin: 100,
+  ultrabold: 800,
+  ultralight: 200,
+};
+
+const baseStyles = StyleSheet.create({
+  root: {
+    includeFontPadding: false,
+    margin: 0,
+    padding: 0,
+  },
+});
+
+function isFiniteNumber(value: unknown): value is number {
+  return typeof value === 'number' && Number.isFinite(value);
+}
+
+function isProcessableColor(color: string) {
+  return processColor(color) != null;
+}
+
+function normalizeFontWeight(weight: TextStyle['fontWeight']): TextStyle['fontWeight'] {
+  if (weight == null) return undefined;
+
+  const weightStr = String(weight).trim().toLowerCase();
+  const compactWeight = weightStr.replace(/[\s_-]/g, '');
+
+  let normalizedNumericWeight: number | undefined;
+
+  if (compactWeight === 'lighter') normalizedNumericWeight = 300;
+  if (compactWeight === 'bolder') normalizedNumericWeight = 700;
+
+  if (normalizedNumericWeight == null && WEB_NAMED_WEIGHT_MAP[compactWeight] != null) {
+    normalizedNumericWeight = WEB_NAMED_WEIGHT_MAP[compactWeight];
+  }
+
+  if (normalizedNumericWeight == null) {
+    const parsed = Number.parseInt(weightStr, 10);
+    if (Number.isNaN(parsed)) return 'normal';
+    normalizedNumericWeight = Math.round(parsed / 100) * 100;
+  }
+
+  const clamped = Math.max(100, Math.min(900, normalizedNumericWeight));
+  const androidApiLevel =
+    typeof Platform.Version === 'number' ? Platform.Version : Number.parseInt(String(Platform.Version), 10);
+
+  if (Platform.OS === 'android' && Number.isFinite(androidApiLevel) && androidApiLevel < 28) {
+    return clamped >= 600 ? 'bold' : 'normal';
+  }
+
+  if (clamped === 400) return 'normal';
+  if (clamped === 700) return 'bold';
+  return String(clamped) as TextStyle['fontWeight'];
+}
+
+function resolveTextWeight(weight: TextWeight): TextStyle['fontWeight'] {
+  switch (weight) {
+    case 'regular':
+      return '400';
+    case 'medium':
+      return '500';
+    case 'semibold':
+      return '600';
+    case 'bold':
+      return '700';
+    case 'heavy':
+      return '800';
+    case 'black':
+      return '900';
+    default:
+      return weight;
+  }
+}
+
+function resolveToneColor(colors: Theme['colors'], tone: TextTone): string | undefined {
+  switch (tone) {
+    case 'inherit':
+      return undefined;
+    case 'primary':
+      return colors.primary;
+    case 'success':
+      return SEMANTIC_COLORS.success;
+    case 'warning':
+      return SEMANTIC_COLORS.warning;
+    case 'danger':
+      return SEMANTIC_COLORS.danger;
+    case 'info':
+      return SEMANTIC_COLORS.info;
+    case 'muted':
+      return colors.muted;
+    case 'subtle':
+      return colors.disabled;
+    case 'disabled':
+      return colors.disabled;
+    case 'inverse':
+    case 'onPrimary':
+      return colors.onPrimary;
+    case 'onSecondary':
+      return colors.onSecondary;
+    case 'default':
+    case 'neutral':
+    default:
+      return colors.onSurface;
+  }
+}
+
+function resolveColorToken(input: string | undefined, fallback: string | undefined, theme: Theme) {
+  if (input == null) return fallback;
+
+  const key = input.trim();
+  if (!key) return fallback;
+
+  const resolved =
+    key === 'default' || key === 'neutral' || key === 'onSurface'
+      ? theme.colors.onSurface
+      : key === 'primary'
+        ? theme.colors.primary
+        : key === 'onPrimary' || key === 'inverse'
+          ? theme.colors.onPrimary
+          : key === 'secondary'
+            ? theme.colors.secondary
+            : key === 'onSecondary'
+              ? theme.colors.onSecondary
+              : key === 'surface'
+                ? theme.colors.surface
+                : key === 'border'
+                  ? theme.colors.border
+                  : key === 'muted'
+                    ? theme.colors.muted
+                    : key === 'subtle' || key === 'disabled'
+                      ? theme.colors.disabled
+                      : SEMANTIC_COLORS[key as keyof typeof SEMANTIC_COLORS] ?? key;
+
+  return isProcessableColor(resolved) ? resolved : fallback;
+}
+
+function resolveTypographyToken(size: TextSizeValue): TypographyToken {
+  if (typeof size === 'string') {
+    return SIZE_TOKENS[size] ?? SIZE_TOKENS.md;
+  }
+
+  if (!isFiniteNumber(size)) return SIZE_TOKENS.md;
+
+  const fontSize = Math.max(0, size);
+  return {
+    fontSize,
+    lineHeight: Math.ceil(fontSize * 1.4),
+  };
+}
+
+function resolveTypographyStyle(size: TextSizeValue, explicitLineHeight: number | undefined): TextStyle {
+  const token = resolveTypographyToken(size);
+  return {
+    fontSize: wp(token.fontSize),
+    lineHeight: wp(isFiniteNumber(explicitLineHeight) ? Math.max(0, explicitLineHeight) : token.lineHeight),
+  };
+}
+
+function normalizeStyleFontWeight(style: StyleProp<TextStyle>): StyleProp<TextStyle> {
+  if (!style) return style;
+
+  const flattened = StyleSheet.flatten(style);
+  const fontWeight = flattened?.fontWeight;
+  if (fontWeight == null) return style;
+
+  const normalizedFontWeight = normalizeFontWeight(fontWeight);
+  if (normalizedFontWeight === fontWeight) return style;
+
+  return [style, { fontWeight: normalizedFontWeight }];
+}
+
+function resolveNumberOfLines(truncate: TextTruncate | undefined, numberOfLines: RNTextProps['numberOfLines']) {
+  if (truncate === true) return 1;
+  if (typeof truncate === 'number' && Number.isFinite(truncate)) {
+    return Math.max(1, Math.floor(truncate));
+  }
+  return numberOfLines;
+}
+
+function resolveAccessibilityState(
+  disabled: boolean,
+  accessibilityState: AccessibilityState | undefined
+): AccessibilityState | undefined {
+  if (!disabled) return accessibilityState;
+  return {
+    ...accessibilityState,
+    disabled: true,
+  };
+}
+
+const TextBase = React.forwardRef<TextRef, TextProps>(function Text(
+  {
+    variant = 'body',
+    size,
+    lineHeight,
+    weight,
+    tone = 'default',
+    color,
+    align,
+    transform,
+    truncate,
+    tabularNumbers = false,
+    disabled = false,
+    style,
+    maxFontSizeMultiplier,
+    allowFontScaling,
+    numberOfLines,
+    ellipsizeMode,
+    accessibilityState,
+    children,
+    ...rest
+  },
+  ref
+) {
+  const theme = useTheme();
+  const { width: viewportWidth } = useWindowDimensions();
+  const variantToken: VariantToken = VARIANT_TOKENS[variant] ?? VARIANT_TOKENS.body;
+  const resolvedSize = size ?? variantToken.size;
+  const resolvedWeight = weight ?? variantToken.weight;
+  const toneColor = resolveToneColor(theme.colors, disabled ? 'disabled' : tone);
+  const resolvedColor = resolveColorToken(color, toneColor, theme);
+  const resolvedNumberOfLines = resolveNumberOfLines(truncate, numberOfLines);
+  const resolvedEllipsizeMode = truncate ? (ellipsizeMode ?? 'tail') : ellipsizeMode;
+  const resolvedAccessibilityState = React.useMemo(
+    () => resolveAccessibilityState(disabled, accessibilityState),
+    [accessibilityState, disabled]
+  );
+
+  const typographyStyle = React.useMemo(
+    () => resolveTypographyStyle(resolvedSize, lineHeight),
+    [lineHeight, resolvedSize, viewportWidth]
+  );
+
+  const semanticStyle = React.useMemo<TextStyle>(() => {
+    const nextStyle: TextStyle = {
+      fontFamily: variantToken.fontFamily,
+      fontVariant: tabularNumbers ? ['tabular-nums'] : undefined,
+      fontWeight: normalizeFontWeight(resolveTextWeight(resolvedWeight)),
+      textAlign: align,
+      textTransform: transform,
+    };
+
+    if (resolvedColor !== undefined) {
+      nextStyle.color = resolvedColor;
+    }
+
+    return nextStyle;
+  }, [
+    align,
+    resolvedColor,
+    resolvedWeight,
+    tabularNumbers,
+    transform,
+    variantToken.fontFamily,
+  ]);
+
+  const normalizedStyle = React.useMemo(() => normalizeStyleFontWeight(style), [style]);
+  const finalStyle = React.useMemo<StyleProp<TextStyle>>(
+    () =>
+      normalizedStyle
+        ? [baseStyles.root, typographyStyle, semanticStyle, normalizedStyle]
+        : [baseStyles.root, typographyStyle, semanticStyle],
+    [normalizedStyle, semanticStyle, typographyStyle]
+  );
+
+  return (
+    <RNText
+      ref={ref}
+      {...rest}
+      accessibilityState={resolvedAccessibilityState}
+      allowFontScaling={allowFontScaling}
+      disabled={disabled}
+      ellipsizeMode={resolvedEllipsizeMode}
+      maxFontSizeMultiplier={
+        allowFontScaling === false ? maxFontSizeMultiplier : (maxFontSizeMultiplier ?? getMaxFontSizeMultiplier())
+      }
+      numberOfLines={resolvedNumberOfLines}
+      style={finalStyle}
+    >
+      {children}
+    </RNText>
+  );
+});
+
+TextBase.displayName = 'Text';
+
+export const Text = React.memo(TextBase);
+Text.displayName = 'Text';