react-native-terra-ui 0.1.0

package/src/components/surface/Surface.tsx

@@ -0,0 +1,100 @@
+import { type ComponentRef, forwardRef } from 'react';
+import type { View, ViewStyle } from 'react-native';
+
+import { useUnistyles } from 'react-native-unistyles';
+
+import { getDefaultRadius, getSurfaceElevation } from '#theme/configure';
+import type { ColorToken, ElevationKey } from '#theme/types';
+
+import { type BorderWidthInput, Box, type BoxProps } from '../box';
+
+/** Background level of a {@link Surface}. */
+export type SurfaceVariant = 'base' | 'raised' | 'sunken' | 'transparent';
+
+export interface SurfaceProps extends Omit<BoxProps, 'bg'> {
+  /** Background surface level. Defaults to `'base'`. */
+  variant?: SurfaceVariant;
+  /**
+   * Drop-shadow depth (platform-aware shadow + Android elevation).
+   * Defaults to `'sm'` for `variant="raised"`, otherwise the configured
+   * surface elevation (`'none'` if unset). Note: a shadow needs a
+   * non-transparent background to render, so `variant="transparent"` shows no
+   * shadow.
+   */
+  elevation?: ElevationKey;
+}
+
+const VARIANT_BG: Record<SurfaceVariant, ColorToken> = {
+  base: 'surface.default',
+  raised: 'surface.raised',
+  sunken: 'surface.sunken',
+  transparent: 'transparent',
+};
+
+/** Variant-aware hairline borders improve edge definition when fills are close. */
+const VARIANT_BORDER: Record<
+  SurfaceVariant,
+  { borderWidth?: BorderWidthInput; borderColor?: ColorToken }
+> = {
+  base: {},
+  raised: { borderWidth: 'hairline', borderColor: 'border.subtle' },
+  sunken: { borderWidth: 'hairline', borderColor: 'border.default' },
+  transparent: {},
+};
+
+const resolveElevation = (
+  variant: SurfaceVariant,
+  elevation?: ElevationKey
+): ElevationKey => {
+  if (elevation !== undefined) return elevation;
+  if (variant === 'raised') return 'sm';
+  return getSurfaceElevation();
+};
+
+/**
+ * Themed container built on {@link Box}. Picks its background from a semantic
+ * surface `variant`, its corner radius from the configured `surface`
+ * default (overridable via `radius`), and an optional drop shadow via
+ * `elevation`. All other Box style-props are accepted.
+ *
+ * @example
+ * ```tsx
+ * <Surface variant="raised" elevation="md" p="4" radius="lg">
+ *   <Text variant="title-sm">Card title</Text>
+ * </Surface>
+ * ```
+ */
+export const Surface = forwardRef<ComponentRef<typeof View>, SurfaceProps>(
+  function Surface(
+    {
+      variant = 'base',
+      elevation,
+      radius,
+      borderWidth,
+      borderColor,
+      style,
+      ...rest
+    },
+    ref
+  ) {
+    const { theme } = useUnistyles();
+    const resolvedElevation = resolveElevation(variant, elevation);
+    const variantBorder = VARIANT_BORDER[variant];
+    const shadowStyle =
+      variant !== 'transparent' && resolvedElevation !== 'none'
+        ? (theme.elevation[resolvedElevation] as ViewStyle)
+        : undefined;
+
+    return (
+      <Box
+        ref={ref}
+        bg={VARIANT_BG[variant]}
+        radius={radius ?? getDefaultRadius('surface')}
+        borderWidth={borderWidth ?? variantBorder.borderWidth}
+        borderColor={borderColor ?? variantBorder.borderColor}
+        style={shadowStyle ? [shadowStyle, style] : style}
+        {...rest}
+      />
+    );
+  }
+);

package/src/components/surface/index.ts

@@ -0,0 +1,2 @@
+export type { SurfaceProps, SurfaceVariant } from './Surface';
+export { Surface } from './Surface';

package/src/components/text/Text.tsx

@@ -0,0 +1,115 @@
+import { type ComponentRef, forwardRef } from 'react';
+import {
+  Text as RNText,
+  type TextProps as RNTextProps,
+  type TextStyle,
+} from 'react-native';
+
+import { useUnistyles } from 'react-native-unistyles';
+import type {
+  ColorToken,
+  FontWeightToken,
+  HeadingTextVariant,
+  RoleTextVariant,
+  TextVariant,
+} from '#theme/types';
+import type { Mutable } from '#types';
+import { resolveThemeColor } from '#utils/resolve-theme-color';
+import { FONT_WEIGHT_VALUE, SYSTEM_FONT } from '#utils/typography';
+
+export type TextAlign = 'left' | 'center' | 'right' | 'justify';
+
+const HEADING_VARIANT_ALIAS: Record<HeadingTextVariant, RoleTextVariant> = {
+  h1: 'headline-lg',
+  h2: 'headline-md',
+  h3: 'title-lg',
+  h4: 'title-md',
+  h5: 'title-sm',
+  h6: 'label-lg',
+};
+
+function resolveTextVariant(variant: TextVariant): RoleTextVariant {
+  return variant in HEADING_VARIANT_ALIAS
+    ? HEADING_VARIANT_ALIAS[variant as HeadingTextVariant]
+    : (variant as RoleTextVariant);
+}
+
+export interface TextProps extends RNTextProps {
+  /** Typographic role. Defaults to `body-md`. */
+  variant?: TextVariant;
+  /** Semantic color token (e.g. `content.secondary`, `status.danger.solid`). */
+  color?: ColorToken;
+  /** Override the variant's default weight. */
+  weight?: FontWeightToken;
+  align?: TextAlign;
+  italic?: boolean;
+  underline?: boolean;
+  strikeThrough?: boolean;
+  /** Truncate to a single line with a trailing ellipsis. */
+  isTruncated?: boolean;
+}
+
+/**
+ * Themed text primitive. Reads its scale from `theme.typography` and resolves
+ * fonts by weight, honoring Dynamic Type with a per-variant scaling cap.
+ */
+export const Text = forwardRef<ComponentRef<typeof RNText>, TextProps>(
+  function Text(
+    {
+      variant = 'body-md',
+      color,
+      weight,
+      align,
+      italic,
+      underline,
+      strikeThrough,
+      isTruncated,
+      style,
+      numberOfLines,
+      ellipsizeMode,
+      maxFontSizeMultiplier,
+      ...rest
+    },
+    ref
+  ) {
+    const { theme } = useUnistyles();
+    const resolvedVariant = resolveTextVariant(variant);
+    const v = theme.typography.variants[resolvedVariant];
+    const effectiveWeight: FontWeightToken = weight ?? v.fontWeight;
+    const fontFamily = theme.typography.fonts[effectiveWeight];
+    const isSystemFont = fontFamily === SYSTEM_FONT;
+
+    const base: Mutable<TextStyle> = {
+      fontSize: v.fontSize,
+      lineHeight: v.lineHeight,
+      letterSpacing: v.letterSpacing,
+      color:
+        resolveThemeColor(color, theme) ??
+        (theme.color as unknown as Record<string, string | undefined>)[
+          'text.default'
+        ] ??
+        '',
+    };
+    // System font: apply numeric weight. Custom font: family encodes the weight.
+    if (isSystemFont) base.fontWeight = FONT_WEIGHT_VALUE[effectiveWeight];
+    else base.fontFamily = fontFamily;
+
+    if (align) base.textAlign = align;
+    if (italic) base.fontStyle = 'italic';
+    if (underline && strikeThrough)
+      base.textDecorationLine = 'underline line-through';
+    else if (underline) base.textDecorationLine = 'underline';
+    else if (strikeThrough) base.textDecorationLine = 'line-through';
+
+    return (
+      <RNText
+        ref={ref}
+        style={[base, style]}
+        maxFontSizeMultiplier={maxFontSizeMultiplier ?? v.maxFontSizeMultiplier}
+        numberOfLines={isTruncated ? 1 : numberOfLines}
+        ellipsizeMode={isTruncated ? 'tail' : ellipsizeMode}
+        {...rest}
+      />
+    );
+  }
+);

package/src/components/text/index.ts

@@ -0,0 +1,2 @@
+export type { TextAlign, TextProps } from './Text';
+export { Text } from './Text';

package/src/components/toast/Toast.tsx

@@ -0,0 +1,477 @@
+import {
+  type ComponentRef,
+  createContext,
+  forwardRef,
+  type ReactNode,
+  useContext,
+  useId,
+  useMemo,
+} from 'react';
+import type { GestureResponderEvent, PressableProps, View } from 'react-native';
+import { Pressable, StyleSheet } from 'react-native';
+
+import { useUnistyles } from 'react-native-unistyles';
+
+import type { TerraIconName, TerraTheme } from '#theme/types';
+
+import { Box } from '../box';
+import { Button, type ButtonProps } from '../button';
+import { Icon, type IconProps } from '../icon';
+import { Surface, type SurfaceProps } from '../surface';
+import { Text, type TextProps } from '../text';
+import type { ToastId as StackToastId, ToastShowOptions } from './types';
+import { hideToast, showToast } from './utils/controller';
+
+export type ToastVariant =
+  | 'default'
+  | 'accent'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger';
+
+type ToastInstanceId = string | number;
+
+export interface ToastControls {
+  hide?: (id: ToastInstanceId) => void;
+  id?: ToastInstanceId;
+}
+
+interface ToastContextValue extends ToastControls {
+  nativeID: string;
+  variant: ToastVariant;
+  onClose?: () => void;
+}
+
+const ToastContext = createContext<ToastContextValue | null>(null);
+
+function useToastContext(): ToastContextValue {
+  const context = useContext(ToastContext);
+  if (!context) {
+    throw new Error(
+      'Toast compound components must be rendered inside <Toast>.'
+    );
+  }
+  return context;
+}
+
+interface ToastColors {
+  bg: string;
+  border: string;
+  title: string;
+  description: string;
+  icon: string;
+  actionBg: string;
+  actionFg: string;
+}
+
+function getToastColors(variant: ToastVariant, theme: TerraTheme): ToastColors {
+  const c = theme.color as unknown as Record<string, string | undefined>;
+  const get = (key: string): string => c[key] ?? '';
+  const base = {
+    bg: get('surface.default'),
+    border: get('border.subtle'),
+    description: get('text.muted'),
+  };
+
+  switch (variant) {
+    case 'accent':
+      return {
+        ...base,
+        title: get('action.fg.subtle'),
+        icon: get('text.accent'),
+        actionBg: get('action.bg.primary'),
+        actionFg: get('action.fg.primary'),
+      };
+    case 'info':
+    case 'success':
+    case 'warning':
+    case 'danger':
+      return {
+        ...base,
+        title: get(`status.bg.${variant}`),
+        icon: get(`status.bg.${variant}`),
+        actionBg: get(`status.bg.${variant}`),
+        actionFg: get(`status.fg.${variant}`),
+      };
+    case 'default':
+      return {
+        ...base,
+        title: get('text.default'),
+        icon: get('text.subtle'),
+        actionBg: get('action.bg.neutral.hover'),
+        actionFg: get('action.fg.neutral'),
+      };
+  }
+}
+
+export interface ToastProps extends Omit<SurfaceProps, 'id' | 'variant'> {
+  /** Visual tone for the toast. Defaults to `default`. */
+  variant?: ToastVariant;
+  /** Optional identifier passed back to `hide` when `Toast.Close` is pressed. */
+  id?: ToastInstanceId;
+  /** Imperative hide callback used by toast queues/providers. */
+  hide?: (id: ToastInstanceId) => void;
+  /** Local close callback used by `Toast.Close`. */
+  onClose?: () => void;
+}
+
+const ToastRoot = forwardRef<ComponentRef<typeof View>, ToastProps>(
+  function Toast(
+    {
+      variant = 'default',
+      id,
+      hide,
+      onClose,
+      children,
+      nativeID: nativeIDProp,
+      style,
+      accessibilityRole = 'alert',
+      ...rest
+    },
+    ref
+  ) {
+    const { theme } = useUnistyles();
+    const generatedNativeID = useId();
+    const nativeID = nativeIDProp ?? String(id ?? generatedNativeID);
+    const colors = getToastColors(variant, theme);
+    const contextValue = useMemo<ToastContextValue>(
+      () => ({ nativeID, variant, id, hide, onClose }),
+      [nativeID, variant, id, hide, onClose]
+    );
+
+    return (
+      <ToastContext.Provider value={contextValue}>
+        <Surface
+          ref={ref}
+          variant="raised"
+          elevation="md"
+          radius="xl"
+          p="4"
+          row
+          align="center"
+          gap="3"
+          accessibilityRole={accessibilityRole}
+          accessibilityLiveRegion="polite"
+          borderWidth="hairline"
+          nativeID={nativeID}
+          style={[
+            styles.root,
+            {
+              backgroundColor: colors.bg,
+              borderColor: colors.border,
+            },
+            style,
+          ]}
+          {...rest}
+        >
+          {children}
+        </Surface>
+      </ToastContext.Provider>
+    );
+  }
+);
+
+export interface ToastTitleProps extends TextProps {}
+
+const ToastTitle = forwardRef<ComponentRef<typeof Text>, ToastTitleProps>(
+  function ToastTitle(
+    {
+      accessibilityRole = 'header',
+      color,
+      nativeID,
+      variant = 'label-lg',
+      weight,
+      ...rest
+    },
+    ref
+  ) {
+    const { theme } = useUnistyles();
+    const { nativeID: rootNativeID, variant: toastVariant } = useToastContext();
+    const colors = getToastColors(toastVariant, theme);
+
+    return (
+      <Text
+        ref={ref}
+        accessibilityRole={accessibilityRole}
+        color={color ?? colors.title}
+        nativeID={nativeID ?? `${rootNativeID}_label`}
+        variant={variant}
+        weight={weight ?? 'semibold'}
+        {...rest}
+      />
+    );
+  }
+);
+
+export interface ToastDescriptionProps extends TextProps {}
+
+const ToastDescription = forwardRef<
+  ComponentRef<typeof Text>,
+  ToastDescriptionProps
+>(function ToastDescription(
+  { color, nativeID, variant = 'body-sm', ...rest },
+  ref
+) {
+  const { theme } = useUnistyles();
+  const { nativeID: rootNativeID, variant: toastVariant } = useToastContext();
+  const colors = getToastColors(toastVariant, theme);
+
+  return (
+    <Text
+      ref={ref}
+      color={color ?? colors.description}
+      nativeID={nativeID ?? `${rootNativeID}_desc`}
+      variant={variant}
+      {...rest}
+    />
+  );
+});
+
+export interface ToastActionProps
+  extends Omit<PressableProps, 'children' | 'disabled' | 'style'> {
+  children?: ReactNode;
+  /** Override the action button colour. Defaults to the parent Toast variant. */
+  variant?: ToastVariant;
+  fullWidth?: boolean;
+  isDisabled?: boolean;
+  size?: 'sm' | 'md' | 'lg';
+  style?: PressableProps['style'];
+}
+
+function renderActionChildren(children: ReactNode, color: string): ReactNode {
+  if (typeof children === 'string' || typeof children === 'number') {
+    return (
+      <Text variant="label-lg" weight="semibold" style={{ color }}>
+        {children}
+      </Text>
+    );
+  }
+  return children;
+}
+
+const ToastAction = forwardRef<
+  ComponentRef<typeof Pressable>,
+  ToastActionProps
+>(function ToastAction(
+  {
+    children,
+    variant,
+    fullWidth = false,
+    isDisabled = false,
+    size = 'sm',
+    style,
+    onPress,
+    ...rest
+  },
+  ref
+) {
+  const { theme } = useUnistyles();
+  const { variant: toastVariant } = useToastContext();
+  const colors = getToastColors(variant ?? toastVariant, theme);
+
+  return (
+    <Pressable
+      ref={ref}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: isDisabled }}
+      disabled={isDisabled}
+      onPress={isDisabled ? undefined : onPress}
+      {...rest}
+      style={(state) => [
+        styles.action,
+        styles[`action_${size}`],
+        fullWidth ? styles.actionFullWidth : null,
+        {
+          backgroundColor: colors.actionBg,
+          opacity:
+            state.pressed && !isDisabled
+              ? theme.opacity.pressed
+              : isDisabled
+                ? theme.opacity.disabled
+                : 1,
+        },
+        typeof style === 'function' ? style(state) : style,
+      ]}
+    >
+      {renderActionChildren(children, colors.actionFg)}
+    </Pressable>
+  );
+});
+
+export interface ToastCloseProps extends Omit<ButtonProps, 'children'> {
+  children?: ReactNode;
+  iconProps?: Omit<IconProps, 'name'>;
+}
+
+const ToastClose = forwardRef<ComponentRef<typeof Button>, ToastCloseProps>(
+  function ToastClose(
+    {
+      children,
+      iconProps,
+      size = 'sm',
+      fullWidth = false,
+      isIconOnly = true,
+      variant = 'ghost',
+      accessibilityLabel = 'Close',
+      onPress,
+      ...rest
+    },
+    ref
+  ) {
+    const { theme } = useUnistyles();
+    const { id, hide, onClose, variant: toastVariant } = useToastContext();
+    const colors = getToastColors(toastVariant, theme);
+    const handlePress = (event: GestureResponderEvent) => {
+      if (id !== undefined) hide?.(id);
+      onClose?.();
+      onPress?.(event);
+    };
+
+    return (
+      <Button
+        ref={ref}
+        accessibilityLabel={accessibilityLabel}
+        fullWidth={fullWidth}
+        isIconOnly={isIconOnly}
+        onPress={handlePress}
+        size={size}
+        compact
+        variant={variant}
+        {...rest}
+      >
+        {children ?? (
+          <Icon
+            name="navigation.close"
+            size={iconProps?.size ?? 20}
+            color={iconProps?.color ?? colors.icon}
+            strokeWidth={iconProps?.strokeWidth}
+            style={iconProps?.style}
+          />
+        )}
+      </Button>
+    );
+  }
+);
+
+export interface ToastIconProps extends Omit<IconProps, 'name'> {
+  name?: TerraIconName;
+}
+
+const VARIANT_ICON: Partial<Record<ToastVariant, TerraIconName>> = {
+  info: 'status.info',
+  success: 'status.success',
+  warning: 'status.warning',
+  danger: 'status.danger',
+};
+
+const ToastIcon = forwardRef<ComponentRef<typeof View>, ToastIconProps>(
+  function ToastIcon({ name, color, size = 20, ...rest }, ref) {
+    const { theme } = useUnistyles();
+    const { variant } = useToastContext();
+    const colors = getToastColors(variant, theme);
+    const iconName = name ?? VARIANT_ICON[variant] ?? 'status.info';
+
+    return (
+      <Icon
+        ref={ref}
+        color={color ?? colors.icon}
+        name={iconName}
+        size={size}
+        {...rest}
+      />
+    );
+  }
+);
+
+export interface DefaultToastProps extends Omit<ToastProps, 'children'> {
+  label?: ReactNode;
+  description?: ReactNode;
+  actionLabel?: ReactNode;
+  onActionPress?: (controls: ToastControls) => void;
+  icon?: ReactNode | false;
+  showCloseButton?: boolean;
+}
+
+export function DefaultToast({
+  label,
+  description,
+  actionLabel,
+  onActionPress,
+  icon,
+  showCloseButton,
+  id,
+  hide,
+  variant = 'default',
+  ...rest
+}: DefaultToastProps) {
+  const shouldRenderIcon = icon !== false && (icon || variant !== 'default');
+  const handleActionPress = () => {
+    onActionPress?.({ id, hide });
+  };
+
+  return (
+    <ToastRoot id={id} hide={hide} variant={variant} {...rest}>
+      {shouldRenderIcon ? (
+        <Box alignSelf="start">{icon ?? <ToastIcon />}</Box>
+      ) : null}
+      <Box flex={1} gap="1">
+        {label ? <ToastTitle>{label}</ToastTitle> : null}
+        {description ? (
+          <ToastDescription>{description}</ToastDescription>
+        ) : null}
+      </Box>
+      {actionLabel ? (
+        <ToastAction onPress={handleActionPress}>{actionLabel}</ToastAction>
+      ) : null}
+      {showCloseButton ? <ToastClose /> : null}
+    </ToastRoot>
+  );
+}
+
+type ToastComponent = typeof ToastRoot & {
+  Title: typeof ToastTitle;
+  Description: typeof ToastDescription;
+  Action: typeof ToastAction;
+  Close: typeof ToastClose;
+  Icon: typeof ToastIcon;
+  show: (options: ToastShowOptions) => StackToastId;
+  hide: (id?: StackToastId | StackToastId[] | 'all') => void;
+};
+
+export const Toast = ToastRoot as ToastComponent;
+Toast.Title = ToastTitle;
+Toast.Description = ToastDescription;
+Toast.Action = ToastAction;
+Toast.Close = ToastClose;
+Toast.Icon = ToastIcon;
+Toast.show = showToast;
+Toast.hide = hideToast;
+
+const styles = StyleSheet.create({
+  root: {
+    alignSelf: 'stretch',
+    minHeight: 64,
+  },
+  action: {
+    alignItems: 'center',
+    alignSelf: 'flex-start',
+    borderRadius: 9999,
+    justifyContent: 'center',
+  },
+  action_sm: {
+    minHeight: 36,
+    paddingHorizontal: 14,
+  },
+  action_md: {
+    minHeight: 44,
+    paddingHorizontal: 16,
+  },
+  action_lg: {
+    minHeight: 52,
+    paddingHorizontal: 20,
+  },
+  actionFullWidth: {
+    alignSelf: 'stretch',
+  },
+});