react-native-terra-ui 0.1.1 → 0.2.0

package/src/components/chip/Chip.tsx

@@ -0,0 +1,444 @@
+import {
+  Children,
+  type ComponentRef,
+  createContext,
+  forwardRef,
+  type ReactNode,
+  useContext,
+} from 'react';
+import { View, type ViewProps } from 'react-native';
+
+import { StyleSheet, withUnistyles } from 'react-native-unistyles';
+
+import type { ColorToken, TerraIconName, TextVariant } from '#theme/types';
+
+import { Icon } from '../icon';
+import { Text } from '../text';
+import type { ChipColor, ChipSize, ChipVariant } from './types';
+import { type CustomChipColors, getCustomColorColors } from './utils';
+
+export interface ChipProps extends ViewProps {
+  size?: ChipSize;
+  variant?: ChipVariant;
+  color?: ChipColor;
+  children?: ReactNode;
+}
+
+// ─── Context (lets Chip.Icon read the resolved foreground + size) ─────────────
+
+interface ChipContextValue {
+  /**
+   * Foreground as a **token** (or a raw literal for a custom color), never a
+   * resolved value — `Text` and `Icon` resolve it against the live theme, so
+   * each owns its own subscription and the label keeps working however the
+   * chip above it is rendered.
+   */
+  color: ColorToken;
+  size: ChipSize;
+}
+
+const ChipContext = createContext<ChipContextValue>({
+  color: 'text.default',
+  size: 'md',
+});
+
+// ─── Colors ─────────────────────────────────────────────────────────────────
+//
+// The chip's own paint (background + border) is a style, so named schemes
+// (primary/secondary/success/warning/danger) are resolved declaratively via
+// unistyles `compoundVariants` on `styles.base` — one entry per (color, variant)
+// pair, straight from the spec's token table.
+//
+// The foreground is *not* a style on this View — it is inherited by the label
+// and icon. It therefore lives here as a token table and is passed down
+// unresolved, so `Text`/`Icon` resolve it against the live theme on every
+// change.
+//
+// A custom color literal (hex/rgb/hsl) isn't a bounded set of options, so it
+// can't be a compound variant condition — see `getCustomColorColors` in
+// `utils.ts` for how it's derived instead.
+
+const SCHEME_NAMES = new Set([
+  'primary',
+  'secondary',
+  'success',
+  'warning',
+  'danger',
+]);
+
+type ChipScheme = 'primary' | 'secondary' | 'success' | 'warning' | 'danger';
+type ChipPaintedVariant = Exclude<ChipVariant, 'ghost'>;
+
+/** Foreground token per (scheme, variant) — mirrors the spec's token table. */
+const FG_TOKEN: Record<ChipScheme, Record<ChipPaintedVariant, ColorToken>> = {
+  primary: {
+    solid: 'action.fg.primary',
+    soft: 'action.fg.primary.subtle',
+    outline: 'text.accent',
+  },
+  secondary: {
+    solid: 'action.fg.secondary',
+    soft: 'action.fg.secondary.subtle',
+    outline: 'text.default',
+  },
+  success: {
+    solid: 'status.success.fg',
+    soft: 'status.success.fg.subtle',
+    outline: 'status.success.fg.subtle',
+  },
+  warning: {
+    solid: 'status.warning.fg',
+    soft: 'status.warning.fg.subtle',
+    outline: 'status.warning.fg.subtle',
+  },
+  danger: {
+    solid: 'status.danger.fg',
+    soft: 'status.danger.fg.subtle',
+    outline: 'status.danger.fg.subtle',
+  },
+};
+
+/** The label/icon color as a token, so children resolve it per theme. */
+function resolveForeground(
+  color: ChipColor,
+  variant: ChipVariant,
+  customColors: CustomChipColors | null
+): ColorToken {
+  if (customColors) return customColors.fg;
+  if (variant === 'ghost') return 'text.default';
+  return FG_TOKEN[color as ChipScheme][variant];
+}
+
+// ─── Label sub-component ───────────────────────────────────────────────────────
+
+const LABEL_VARIANT: Record<ChipSize, TextVariant> = {
+  sm: 'label-sm',
+  md: 'label-md',
+  lg: 'label-lg',
+};
+
+const ChipLabel = ({ children }: { children: ReactNode }) => {
+  const { color, size } = useContext(ChipContext);
+  return (
+    <Text variant={LABEL_VARIANT[size]} weight="semibold" color={color}>
+      {children}
+    </Text>
+  );
+};
+
+// ─── Icon sub-component ────────────────────────────────────────────────────────
+
+const ICON_SIZE: Record<ChipSize, number> = {
+  sm: 12,
+  md: 14,
+  lg: 16,
+};
+
+export interface ChipIconProps extends Omit<ViewProps, 'children'> {
+  name: TerraIconName;
+  size?: number;
+  color?: ColorToken;
+  strokeWidth?: number;
+}
+
+const ChipIcon = ({
+  name,
+  size: sizeProp,
+  color,
+  strokeWidth,
+  style,
+  ...rest
+}: ChipIconProps) => {
+  const { color: contextColor, size } = useContext(ChipContext);
+
+  return (
+    <Icon
+      name={name}
+      color={color || contextColor}
+      size={sizeProp ?? ICON_SIZE[size]}
+      strokeWidth={strokeWidth}
+      style={style}
+      {...rest}
+    />
+  );
+};
+
+function renderChildren(children: ReactNode): ReactNode {
+  return Children.map(children, (child) => {
+    if (typeof child === 'string') {
+      return child.trim().length > 0 ? <ChipLabel>{child}</ChipLabel> : null;
+    }
+    if (typeof child === 'number') {
+      return <ChipLabel>{child}</ChipLabel>;
+    }
+    return child;
+  });
+}
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+const ChipRoot = forwardRef<ComponentRef<typeof View>, ChipProps>(function Chip(
+  {
+    size = 'md',
+    variant = 'soft',
+    color = 'secondary',
+    children,
+    style,
+    ...rest
+  },
+  ref
+) {
+  // Compound variants only match the 5 named schemes above — an arbitrary
+  // literal never matches one, so it's cast to satisfy `useVariants`'s
+  // literal-union type while still comparing against the real value below.
+  styles.useVariants({ color: color as ChipScheme, variant, size });
+
+  const isCustomColor = variant !== 'ghost' && !SCHEME_NAMES.has(color);
+  const customColors = isCustomColor
+    ? getCustomColorColors(color, variant as 'solid' | 'soft' | 'outline')
+    : null;
+
+  const fg = resolveForeground(color, variant, customColors);
+
+  return (
+    <ChipContext.Provider value={{ color: fg, size }}>
+      <View
+        ref={ref}
+        style={[
+          styles.base,
+          customColors
+            ? {
+                backgroundColor: customColors.bg,
+                borderColor: customColors.border,
+                borderWidth: customColors.borderWidth,
+              }
+            : null,
+          style,
+        ]}
+        {...rest}
+      >
+        {renderChildren(children)}
+      </View>
+    </ChipContext.Provider>
+  );
+});
+
+type ChipComponent = typeof ChipRoot & {
+  Icon: typeof ChipIcon;
+};
+
+// Subscribes the chip to theme changes. The background below comes from
+// `compoundVariants`, which unistyles applies straight to the native node when
+// the theme switches — no re-render, so React goes on believing the node holds
+// the previous theme's value. React Native only mutates a node when newly
+// rendered props differ from the last ones it rendered, so a later variant
+// change that computes a value equal to that stale record emits no update at
+// all, and the node keeps whatever the theme switch painted. That is reachable
+// whenever one colour fills two roles across themes — an accent equal to
+// another theme's `action.bg.secondary.subtle`, say — and it shows up as a
+// deselected chip still wearing the selected background.
+//
+// Re-rendering on a theme switch commits the new value there and then, so no
+// stale record survives to collide. `Text` already subscribes this way for its
+// colour; this gives the chip's own paint the same guarantee. The cast keeps
+// `ChipProps` and the ref, which `withUnistyles` widens to `Partial<{}>`.
+export const Chip = withUnistyles(ChipRoot) as ChipComponent;
+Chip.Icon = ChipIcon;
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+// One compound variant per (color, variant) cell of the spec's token table —
+// `variants` below only registers the axis names/options for the type
+// system; the actual bg/border values all come from `compoundVariants`.
+// `size` has no cross-axis interaction, so it's a plain variant.
+//
+// Foreground is deliberately absent: it belongs to the label and icon, not to
+// this View, and is handed to them as a token via `FG_TOKEN` / context.
+const styles = StyleSheet.create((theme) => {
+  const c = theme.color;
+
+  return {
+    base: {
+      flexDirection: 'row',
+      alignItems: 'center',
+      alignSelf: 'flex-start',
+      borderRadius: theme.radius.full,
+      variants: {
+        size: {
+          sm: {
+            minHeight: 24,
+            paddingVertical: 6,
+            paddingHorizontal: 12,
+            gap: 4,
+          },
+          md: {
+            minHeight: 26,
+            paddingVertical: 8,
+            paddingHorizontal: 14,
+            gap: 4,
+          },
+          lg: {
+            minHeight: 28,
+            paddingVertical: 8,
+            paddingHorizontal: 16,
+            gap: 4,
+          },
+        },
+        color: {
+          primary: {},
+          secondary: {},
+          success: {},
+          warning: {},
+          danger: {},
+        },
+        variant: {
+          solid: {},
+          soft: {},
+          outline: {},
+          ghost: {
+            backgroundColor: 'transparent',
+            borderColor: 'transparent',
+            borderWidth: 0,
+          },
+        },
+      },
+      compoundVariants: [
+        {
+          color: 'primary',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['action.bg.primary'],
+            borderColor: c['action.bg.primary'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'primary',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['action.bg.primary.subtle'],
+            borderColor: c['action.bg.primary.subtle'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'primary',
+          variant: 'outline',
+          styles: {
+            backgroundColor: 'transparent',
+            borderColor: c['border.accent'],
+            borderWidth: 1,
+          },
+        },
+        {
+          color: 'secondary',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['action.bg.secondary'],
+            borderColor: c['action.bg.secondary'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'secondary',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['action.bg.secondary.subtle'],
+            borderColor: c['action.bg.secondary.subtle'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'secondary',
+          variant: 'outline',
+          styles: {
+            backgroundColor: 'transparent',
+            borderColor: c['border.default'],
+            borderWidth: 1,
+          },
+        },
+        {
+          color: 'success',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.success.bg'],
+            borderColor: c['status.success.bg'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'success',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.success.bg.subtle'],
+            borderColor: c['status.success.bg.subtle'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'success',
+          variant: 'outline',
+          styles: {
+            backgroundColor: 'transparent',
+            borderColor: c['status.success.border'],
+            borderWidth: 1,
+          },
+        },
+        {
+          color: 'warning',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.warning.bg'],
+            borderColor: c['status.warning.bg'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'warning',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.warning.bg.subtle'],
+            borderColor: c['status.warning.bg.subtle'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'warning',
+          variant: 'outline',
+          styles: {
+            backgroundColor: 'transparent',
+            borderColor: c['status.warning.border'],
+            borderWidth: 1,
+          },
+        },
+        {
+          color: 'danger',
+          variant: 'solid',
+          styles: {
+            backgroundColor: c['status.danger.bg'],
+            borderColor: c['status.danger.bg'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'danger',
+          variant: 'soft',
+          styles: {
+            backgroundColor: c['status.danger.bg.subtle'],
+            borderColor: c['status.danger.bg.subtle'],
+            borderWidth: 0,
+          },
+        },
+        {
+          color: 'danger',
+          variant: 'outline',
+          styles: {
+            backgroundColor: 'transparent',
+            borderColor: c['status.danger.border'],
+            borderWidth: 1,
+          },
+        },
+      ],
+    },
+  };
+});

package/src/components/chip/index.ts

@@ -0,0 +1,3 @@
+export type { ChipIconProps, ChipProps } from './Chip';
+export { Chip } from './Chip';
+export type { ChipColor, ChipSize, ChipVariant } from './types';

package/src/components/chip/types.ts

@@ -0,0 +1,15 @@
+export type ChipSize = 'sm' | 'md' | 'lg';
+export type ChipVariant = 'solid' | 'soft' | 'outline' | 'ghost';
+
+/**
+ * Semantic color scheme, or a raw CSS color literal (`#fff`, `rgb(...)`, `hsl(...)`).
+ * Has no effect when `variant="ghost"` — ghost always renders `text.default`.
+ */
+export type ChipColor =
+  | 'primary'
+  | 'secondary'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  // literals last so scheme-name autocomplete still surfaces
+  | (string & {});

package/src/components/chip/utils.ts

@@ -0,0 +1,34 @@
+import { readableOn, withAlpha } from '#utils/color-utils';
+
+// A custom color literal (hex/rgb/hsl) can't be a unistyles compound variant
+// condition (it's not a bounded set of options), so it's derived here
+// instead, the same way `utils/accent-utils.ts` expands a single hue into a
+// full color scheme.
+
+export interface CustomChipColors {
+  bg: string;
+  border: string;
+  borderWidth: number;
+  fg: string;
+}
+
+const CUSTOM_COLOR_SOFT_ALPHA = 0.16;
+
+export function getCustomColorColors(
+  literal: string,
+  variant: 'solid' | 'soft' | 'outline'
+): CustomChipColors {
+  if (variant === 'outline') {
+    return { bg: 'transparent', border: literal, borderWidth: 1, fg: literal };
+  }
+  if (variant === 'soft') {
+    const bg = withAlpha(literal, CUSTOM_COLOR_SOFT_ALPHA);
+    return { bg, border: bg, borderWidth: 0, fg: literal };
+  }
+  return {
+    bg: literal,
+    border: literal,
+    borderWidth: 0,
+    fg: readableOn(literal),
+  };
+}

package/src/components/empty-state/EmptyState.tsx

@@ -0,0 +1,209 @@
+import { type ComponentRef, forwardRef, type ReactNode } from 'react';
+import { View, type ViewProps } from 'react-native';
+
+import { StyleSheet } from 'react-native-unistyles';
+
+import type { ColorToken, TerraIconName, TextVariant } from '#theme/types';
+
+import { Icon } from '../icon';
+import { Text } from '../text';
+import type { EmptyStateSize } from './types';
+
+export interface EmptyStateProps extends Omit<ViewProps, 'children'> {
+  /** Icon rendered in the circular badge above the title. */
+  icon?: TerraIconName;
+  /** Icon tint. Defaults to `text.subtle`. */
+  iconColor?: ColorToken;
+  /**
+   * Replaces the icon badge entirely — an illustration, `Image`, or any custom
+   * node. Takes precedence over `icon`.
+   */
+  media?: ReactNode;
+  /** Headline. A bare string is wrapped in the size's title `Text`. */
+  title: ReactNode;
+  /** Supporting copy under the title. A bare string gets a muted body `Text`. */
+  description?: ReactNode;
+  /** Call to action — typically a `Button`, or a fragment of two. */
+  action?: ReactNode;
+  size?: EmptyStateSize;
+  /**
+   * Expand to fill the parent (`flex: 1` plus cross-axis stretch) so the
+   * content sits in the middle of it rather than hugging its own height.
+   * Inside a `ScrollView`, put the flex on `contentContainerStyle` instead —
+   * a scroll view's children cannot flex against its content size.
+   */
+  fill?: boolean;
+}
+
+// ─── Per-size lookups ─────────────────────────────────────────────────────────
+//
+// These feed *props* (a `Text` variant, an `Icon` size in dp), not styles, so
+// they stay plain tables here; everything that is a style is a unistyles
+// variant below.
+
+const TYPOGRAPHY: Record<
+  EmptyStateSize,
+  { title: TextVariant; description: TextVariant }
+> = {
+  sm: { title: 'title-sm', description: 'body-sm' },
+  md: { title: 'title-md', description: 'body-md' },
+  lg: { title: 'title-lg', description: 'body-lg' },
+};
+
+const ICON_SIZE: Record<EmptyStateSize, number> = {
+  sm: 28,
+  md: 34,
+  lg: 44,
+};
+
+/** Wraps a bare string/number in the slot's themed `Text`; elements pass through. */
+function renderSlot(
+  node: ReactNode,
+  wrap: (value: ReactNode) => ReactNode
+): ReactNode {
+  if (node === null || node === undefined || node === false) return null;
+  return typeof node === 'string' || typeof node === 'number'
+    ? wrap(node)
+    : node;
+}
+
+/**
+ * Centered placeholder for a screen, list, or panel with nothing to show:
+ * a large icon, a title, optional supporting copy, and an optional action.
+ *
+ * @example
+ * ```tsx
+ * <EmptyState
+ *   icon="status.info"
+ *   title="No results"
+ *   description="Try a different search term or clear your filters."
+ *   action={<Button onPress={reset}>Clear filters</Button>}
+ * />
+ * ```
+ */
+export const EmptyState = forwardRef<
+  ComponentRef<typeof View>,
+  EmptyStateProps
+>(function EmptyState(
+  {
+    icon,
+    iconColor = 'text.default',
+    media,
+    title,
+    description,
+    action,
+    size = 'md',
+    fill = false,
+    style,
+    ...rest
+  },
+  ref
+) {
+  styles.useVariants({ size, fill });
+
+  const typography = TYPOGRAPHY[size];
+
+  return (
+    <View ref={ref} style={[styles.root, style]} {...rest}>
+      {media ??
+        (icon ? (
+          <View style={styles.iconBadge}>
+            <Icon name={icon} size={ICON_SIZE[size]} color={iconColor} />
+          </View>
+        ) : null)}
+
+      <View style={styles.text}>
+        {renderSlot(title, (value) => (
+          <Text weight="semibold" variant={typography.title} align="center">
+            {value}
+          </Text>
+        ))}
+        {renderSlot(description, (value) => (
+          <Text
+            variant={typography.description}
+            color="text.subtle"
+            align="center"
+          >
+            {value}
+          </Text>
+        ))}
+      </View>
+
+      {action ? <View style={styles.actions}>{action}</View> : null}
+    </View>
+  );
+});
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+//
+// `size` and `fill` are the only style axes, and neither interacts with the
+// other, so a plain variant per element does the whole job — no compound
+// variants needed.
+// The badge is sized by padding around the icon rather than an explicit
+// width/height, which keeps it a perfect circle on the spacing scale.
+const styles = StyleSheet.create((theme) => ({
+  root: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    variants: {
+      // `alignSelf` matters as much as `flex` here: a column parent hands its
+      // children the cross-axis size of their content unless they stretch, so
+      // without it the state would fill the height and still be pinned to the
+      // width of its longest line.
+      fill: {
+        true: { flex: 1, alignSelf: 'stretch' },
+        false: {},
+      },
+      size: {
+        sm: {
+          gap: theme.spacing['2'],
+          paddingVertical: theme.spacing['4'],
+          paddingHorizontal: theme.spacing['4'],
+        },
+        md: {
+          gap: theme.spacing['3'],
+          paddingVertical: theme.spacing['6'],
+          paddingHorizontal: theme.spacing['6'],
+        },
+        lg: {
+          gap: theme.spacing['4'],
+          paddingVertical: theme.spacing['8'],
+          paddingHorizontal: theme.spacing['6'],
+        },
+      },
+    },
+  },
+  iconBadge: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: theme.color['action.bg.primary.subtle'],
+    borderRadius: theme.radius.full,
+    variants: {
+      size: {
+        sm: { padding: theme.spacing['3'] },
+        md: { padding: theme.spacing['4'] },
+        lg: { padding: theme.spacing['5'] },
+      },
+    },
+  },
+  text: {
+    alignItems: 'center',
+    variants: {
+      size: {
+        sm: { gap: theme.spacing['1'] },
+        md: { gap: theme.spacing['1'] },
+        lg: { gap: theme.spacing['2'] },
+      },
+    },
+  },
+  actions: {
+    alignItems: 'center',
+    variants: {
+      size: {
+        sm: { gap: theme.spacing['2'], marginTop: theme.spacing['1'] },
+        md: { gap: theme.spacing['3'], marginTop: theme.spacing['2'] },
+        lg: { gap: theme.spacing['3'], marginTop: theme.spacing['2'] },
+      },
+    },
+  },
+}));