react-native-terra-ui 0.1.0 → 0.2.0

package/src/components/toolbar/Toolbar.tsx

@@ -0,0 +1,353 @@
+import {
+  Children,
+  type ComponentRef,
+  createContext,
+  forwardRef,
+  type ReactNode,
+  useContext,
+  useMemo,
+} from 'react';
+import {
+  Pressable,
+  type PressableProps,
+  View,
+  type ViewProps,
+} from 'react-native';
+
+import { StyleSheet } from 'react-native-unistyles';
+
+import type { ColorToken, SpacingKey, TerraIconName } from '#theme/types';
+import { resolveThemeColor } from '#utils/resolve-theme-color';
+
+import { Icon } from '../icon';
+import { Text } from '../text';
+
+// ─── Context (lets Toolbar.Button inherit the group's paint) ──────────────────
+//
+// Both colors are unresolved **tokens**, never resolved values — the button and
+// its `Text`/`Icon` resolve them against the live theme, so each leaf owns its
+// own subscription and keeps repainting on a scheme switch however the group
+// above it was rendered. Same contract as `ChipContext`.
+
+interface ToolbarGroupContextValue {
+  /** Fill token for a button's own capsule. A group sets `'transparent'`. */
+  background: ColorToken;
+  /** Foreground token inherited by each button's icon and label. */
+  tint: ColorToken;
+  /**
+   * True inside a {@link ToolbarGroup}. Adjacent buttons share a cell edge, so
+   * a horizontal `hitSlop` would reach into a neighbour's bounds and steal
+   * taps from it — grouped buttons expand vertically only.
+   */
+  isGrouped: boolean;
+}
+
+/** Non-null default, so a bare `Toolbar.Button` still paints its own circle. */
+const ToolbarGroupContext = createContext<ToolbarGroupContextValue>({
+  background: 'surface.default',
+  tint: 'text.default',
+  isGrouped: false,
+});
+
+/** Square cell of an icon-only item, in dp. */
+const ITEM_SIZE = 40;
+
+/** Touch expansion outside the cell, in dp. */
+const HIT_SLOP = 8;
+
+/** Typographic role of a text item's label. */
+const LABEL_VARIANT = 'label-md';
+
+// ─── Button ───────────────────────────────────────────────────────────────────
+
+interface ToolbarButtonBaseProps
+  extends Omit<PressableProps, 'children' | 'style'> {
+  /** Icon to render, before the label when both are given. */
+  icon?: TerraIconName;
+  /** Icon size in density-independent pixels. Defaults to `20`. */
+  iconSize?: number;
+  /**
+   * Foreground token for the icon and label. Defaults to the group's `tint`,
+   * or `text.default` outside a group.
+   */
+  tint?: ColorToken;
+  /**
+   * Fill. Defaults to `surface.default` standalone, and to `transparent`
+   * inside a {@link ToolbarGroup}, which paints the shared capsule instead.
+   * Set it explicitly to opt back out of the group's fill.
+   */
+  background?: ColorToken;
+  /**
+   * Label content. A `string` or `number` renders as themed text in the
+   * button's `tint`; anything else renders as given. The cell grows
+   * horizontally to fit, so a text item is a pill rather than a circle.
+   */
+  children?: ReactNode;
+  /**
+   * Merged over the base style, so a single item can be repositioned (e.g.
+   * pinned over a hero image) without a wrapper view. Supports `Pressable`'s
+   * function form for press-state styling.
+   */
+  style?: PressableProps['style'];
+}
+
+/**
+ * An icon-only button has no visible text, so it must carry an
+ * `accessibilityLabel`; one with children may rely on them instead.
+ */
+export type ToolbarButtonProps = ToolbarButtonBaseProps &
+  (
+    | { children: ReactNode; accessibilityLabel?: string }
+    | { icon: TerraIconName; accessibilityLabel: string }
+  );
+
+/**
+ * An action inside a toolbar — a circular icon button, a text pill, or both.
+ * Paints its own capsule standalone, and goes transparent inside a
+ * {@link ToolbarGroup} so the group's shared capsule shows through.
+ *
+ * @example
+ * ```tsx
+ * <Toolbar.Button icon="share" accessibilityLabel="Share" onPress={share} />
+ * <Toolbar.Button onPress={save}>Save</Toolbar.Button>
+ * ```
+ */
+export function ToolbarButton({
+  icon,
+  iconSize = 20,
+  tint,
+  background,
+  children,
+  accessibilityLabel,
+  onPress,
+  hitSlop = HIT_SLOP,
+  style,
+  ...rest
+}: ToolbarButtonProps) {
+  const {
+    background: groupBackground,
+    tint: groupTint,
+    isGrouped,
+  } = useContext(ToolbarGroupContext);
+
+  // Tokens, not resolved values: `Icon` and `Text` each resolve against the
+  // live theme, so they keep their own subscriptions.
+  const fg = tint ?? groupTint;
+  const bg = background ?? groupBackground;
+  const shape = Children.count(children) > 0 ? 'label' : 'icon';
+
+  styles.useVariants({ shape, grouped: isGrouped });
+
+  // Read during render rather than inside the `style` callback below. The
+  // callback can run after sibling buttons have rendered, and `useVariants` is
+  // set per render pass, so resolving in there risks picking up whichever
+  // sibling called it last. Reading here pins this instance's variants. (The
+  // Jest mock resolves both spellings identically, so the difference only shows
+  // on a device — hence the comment rather than a test.)
+  const cell = styles.button;
+
+  return (
+    <Pressable
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="button"
+      hitSlop={hitSlop}
+      onPress={onPress}
+      {...rest}
+      style={(state) => [
+        cell,
+        styles.fill(bg, state.pressed),
+        typeof style === 'function' ? style(state) : style,
+      ]}
+    >
+      {icon !== undefined && <Icon size={iconSize} color={fg} name={icon} />}
+      {renderLabel(children, fg)}
+    </Pressable>
+  );
+}
+
+/** Auto-wraps text children in the button's tint, as `Chip` does its label. */
+function renderLabel(children: ReactNode, tint: ColorToken): ReactNode {
+  return Children.map(children, (child) => {
+    if (typeof child === 'string') {
+      return child.trim().length > 0 ? (
+        <Text variant={LABEL_VARIANT} color={tint} weight="bold">
+          {child}
+        </Text>
+      ) : null;
+    }
+    if (typeof child === 'number') {
+      return (
+        <Text variant={LABEL_VARIANT} color={tint} weight="bold">
+          {child}
+        </Text>
+      );
+    }
+    return child;
+  });
+}
+
+// ─── Group ────────────────────────────────────────────────────────────────────
+
+export interface ToolbarGroupProps extends ViewProps {
+  /** Capsule fill. Defaults to `surface.default`. */
+  background?: ColorToken;
+  /**
+   * Foreground token inherited by every item's icon and label. Defaults to
+   * `text.default`; a per-item `tint` still wins.
+   */
+  tint?: ColorToken;
+
+  children?: ReactNode;
+}
+
+/**
+ * Wraps several {@link ToolbarButton}s in one shared capsule — the iOS
+ * `ToolbarItemGroup` look. Children drop their individual circular fill and
+ * inherit the group's, so the row reads as a single segmented pill.
+ *
+ * No height of its own: the capsule takes the height of its tallest child, and
+ * its full radius clamps to half of that for an exact stadium.
+ *
+ * @example
+ * ```tsx
+ * <Toolbar.Group>
+ *   <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
+ *   <Toolbar.Button icon="download" accessibilityLabel="Save" onPress={save} />
+ * </Toolbar.Group>
+ * ```
+ */
+export const ToolbarGroup = forwardRef<
+  ComponentRef<typeof View>,
+  ToolbarGroupProps
+>(function ToolbarGroup(
+  {
+    background = 'surface.default',
+    tint = 'text.default',
+    children,
+    style,
+    ...rest
+  },
+  ref
+) {
+  const context = useMemo<ToolbarGroupContextValue>(
+    () => ({ background: 'transparent', tint, isGrouped: true }),
+    [tint]
+  );
+
+  return (
+    <ToolbarGroupContext.Provider value={context}>
+      <View ref={ref} style={[styles.capsule(background), style]} {...rest}>
+        {children}
+      </View>
+    </ToolbarGroupContext.Provider>
+  );
+});
+
+// ─── Root ─────────────────────────────────────────────────────────────────────
+
+export interface ToolbarProps extends ViewProps {
+  /**
+   * Space between groups and standalone items. Defaults to `'2'` (8dp) — the
+   * separator between a capsule and an adjacent standalone item.
+   */
+  gap?: SpacingKey;
+  children?: ReactNode;
+}
+
+/**
+ * A row of {@link ToolbarGroup}s and standalone {@link ToolbarButton}s. The
+ * header's `LeftToolbar` / `RightToolbar` slots supply one automatically, so
+ * you only need to render it yourself when placing a toolbar elsewhere — over
+ * a hero image, or floating above content.
+ *
+ * @example
+ * ```tsx
+ * <Toolbar style={{ position: 'absolute', right: 16, bottom: 24 }}>
+ *   <Toolbar.Group>
+ *     <Toolbar.Button icon="add" accessibilityLabel="Add" onPress={add} />
+ *     <Toolbar.Button icon="download" accessibilityLabel="Save" onPress={save} />
+ *   </Toolbar.Group>
+ *   <Toolbar.Button icon="share" accessibilityLabel="Share" onPress={share} />
+ * </Toolbar>
+ * ```
+ */
+const ToolbarRoot = forwardRef<ComponentRef<typeof View>, ToolbarProps>(
+  function Toolbar({ gap = '2', children, style, ...rest }, ref) {
+    return (
+      <View ref={ref} style={[styles.row(gap), style]} {...rest}>
+        {children}
+      </View>
+    );
+  }
+);
+
+type ToolbarComponent = typeof ToolbarRoot & {
+  Group: typeof ToolbarGroup;
+  Button: typeof ToolbarButton;
+};
+
+export const Toolbar = ToolbarRoot as ToolbarComponent;
+Toolbar.Group = ToolbarGroup;
+Toolbar.Button = ToolbarButton;
+
+// ─── Styles ───────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create((theme) => ({
+  row: (gap: SpacingKey) => ({
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: theme.spacing[gap],
+  }),
+  // `background` is an open `ColorToken` — it accepts raw literals, so it cannot
+  // be enumerated as a variant. Resolving inside the factory keeps the fill tied
+  // to the live theme.
+  capsule: (background: ColorToken) => ({
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: theme.spacing['5'],
+    paddingHorizontal: 10,
+    borderRadius: theme.radius.full,
+    backgroundColor: resolveThemeColor(background, theme),
+    borderWidth: StyleSheet.hairlineWidth,
+    borderColor: theme.color['border.subtle'],
+  }),
+  // Geometry is two finite axes, so it belongs in `variants` rather than in
+  // conditionals: an icon-only cell is an exact square, a labelled one keeps the
+  // height and grows; a grouped cell drops its own padding because the capsule
+  // supplies it.
+  button: {
+    height: ITEM_SIZE,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    borderRadius: theme.radius.full,
+    variants: {
+      shape: {
+        icon: { width: ITEM_SIZE },
+        label: { gap: theme.spacing['1'] },
+      },
+      grouped: {
+        true: { paddingHorizontal: 0 },
+        false: {
+          minWidth: ITEM_SIZE,
+          paddingHorizontal: 10,
+          borderWidth: StyleSheet.hairlineWidth,
+          borderColor: theme.color['border.subtle'],
+        },
+      },
+    },
+    compoundVariants: [
+      {
+        shape: 'icon',
+        grouped: true,
+        styles: { width: undefined },
+      },
+    ],
+  },
+  // Split from `button` so the open-ended fill and the press state stay in the
+  // stylesheet without turning the geometry into a dynamic function too.
+  fill: (background: ColorToken, pressed: boolean) => ({
+    backgroundColor: resolveThemeColor(background, theme),
+    opacity: pressed ? theme.opacity.pressed : 1,
+  }),
+}));

package/src/components/toolbar/index.ts

@@ -0,0 +1,6 @@
+export type {
+  ToolbarButtonProps,
+  ToolbarGroupProps,
+  ToolbarProps,
+} from './Toolbar';
+export { Toolbar } from './Toolbar';

package/src/context/ThemeProvider.tsx

@@ -6,10 +6,9 @@ import {
   useMemo,
   useState,
 } from 'react';
-
+import { SafeAreaProvider } from 'react-native-safe-area-context';
 import { useUnistyles } from 'react-native-unistyles';
-
-import { configureTerraUI, getIsConfigured } from '../theme/configure';
+import { configureTerraUI, getIsConfigured } from '../theme/registry';
 import { applyAccent, applyScheme, getCurrentAccent } from '../theme/runtime';
 import type { Scheme, TerraTheme } from '../theme/types';
 
@@ -50,7 +49,9 @@ export const TerraUIProvider = ({ children }: PropsWithChildren) => {
   );
 
   return (
-    <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>
+    <ThemeContext.Provider value={value}>
+      <SafeAreaProvider>{children}</SafeAreaProvider>
+    </ThemeContext.Provider>
   );
 };
 

package/src/{components/icon/utils.tsx → theme/defaults/icons.tsx}

@@ -4,7 +4,7 @@ import type {
   TerraIconComponent,
   TerraIconProps,
   TerraSemanticIconName,
-} from '#theme/types';
+} from '../types';
 
 const DEFAULT_SIZE = 20;
 const DEFAULT_COLOR = '#000000';

package/src/theme/defaults/image.tsx

@@ -0,0 +1,34 @@
+import { createElement } from 'react';
+import { Image } from 'react-native';
+
+import type { TerraImageComponent, TerraImageContentFit } from '../types';
+
+const CONTENT_FIT_MAP = {
+  cover: 'cover',
+  contain: 'contain',
+  fill: 'stretch',
+} as const satisfies Record<
+  TerraImageContentFit,
+  'cover' | 'contain' | 'stretch'
+>;
+
+/** Default image implementation, backed by React Native's `Image`. */
+export const defaultImage: TerraImageComponent = ({
+  contentFit = 'cover',
+  source,
+  style,
+  accessibilityLabel,
+  placeholder,
+  onError,
+}) =>
+  createElement(Image, {
+    source,
+    style,
+    accessibilityLabel,
+    // RN splits "show this until loaded" across two platform-specific props:
+    // `defaultSource` (iOS only) and `loadingIndicatorSource` (Android only).
+    defaultSource: placeholder,
+    loadingIndicatorSource: placeholder,
+    resizeMode: CONTENT_FIT_MAP[contentFit],
+    onError: onError ? () => onError() : undefined,
+  });

package/src/theme/index.ts

@@ -23,7 +23,7 @@ export {
   getRequiredIcon,
   getSurfaceElevation,
   resolveTheme,
-} from './configure';
+} from './registry';
 export { applyAccent, applyScheme, getCurrentAccent } from './runtime';
 // ─── Default themes ───────────────────────────────────────────────────────────
 export { defaultDarkTheme, defaultLightTheme } from './theme';

package/src/theme/{configure.ts → registry.ts}

@@ -1,12 +1,16 @@
-import { createElement } from 'react';
-import { Image } from 'react-native';
 import { StyleSheet } from 'react-native-unistyles';
 
-import { defaultIcons } from '#components/icon/utils';
 import { normalizeAccent } from '#utils/accent-utils';
 import { deepMerge } from '#utils/deep-merge';
 
-import { buildRadiusScale, defaultDarkTheme, defaultLightTheme } from './theme';
+import { defaultIcons } from './defaults/icons';
+import { defaultImage } from './defaults/image';
+import {
+  buildRadiusScale,
+  buildSpacingScale,
+  defaultDarkTheme,
+  defaultLightTheme,
+} from './theme';
 import type {
   ComponentDefaults,
   DefaultRadiusToken,
@@ -17,38 +21,11 @@ import type {
   TerraConfig,
   TerraIconComponent,
   TerraImageComponent,
-  TerraImageContentFit,
   TerraSemanticIconName,
   TerraTheme,
   TerraThemeOverride,
 } from './types';
 
-// ─── Default image component ──────────────────────────────────────────────────
-
-const CONTENT_FIT_MAP = {
-  cover: 'cover',
-  contain: 'contain',
-  fill: 'stretch',
-} as const satisfies Record<
-  TerraImageContentFit,
-  'cover' | 'contain' | 'stretch'
->;
-
-const DefaultImage: TerraImageComponent = ({
-  contentFit = 'cover',
-  source,
-  style,
-  accessibilityLabel,
-  onError,
-}) =>
-  createElement(Image, {
-    source,
-    style,
-    accessibilityLabel,
-    resizeMode: CONTENT_FIT_MAP[contentFit],
-    onError: onError ? () => onError() : undefined,
-  });
-
 // ─── Radius / elevation defaults ─────────────────────────────────────────────
 
 /** Fallback when a component's radius is not configured. */
@@ -94,7 +71,7 @@ const registry: Registry = {
   defaultRadius: resolveDefaultRadius(),
   surfaceElevation: DEFAULT_ELEVATION,
   icons: {},
-  imageComponent: DefaultImage,
+  imageComponent: defaultImage,
   configured: false,
 };
 
@@ -143,7 +120,7 @@ const mergeThemeOverride = (
 ): TerraTheme => {
   if (!override) return theme;
 
-  const { radius, ...rest } = override;
+  const { radius, spacing, ...rest } = override;
   let next = deepMerge(theme, rest);
 
   if (radius) {
@@ -154,6 +131,14 @@ const mergeThemeOverride = (
     next = deepMerge(next, { radius: radiusTokens });
   }
 
+  if (spacing) {
+    const { base, ...spacingTokens } = spacing;
+    if (base != null) {
+      next = deepMerge(next, { spacing: buildSpacingScale(base) });
+    }
+    next = deepMerge(next, { spacing: spacingTokens });
+  }
+
   return next;
 };
 
@@ -187,7 +172,7 @@ export function configureTerraUI(config: TerraConfig = {}): void {
   registry.surfaceElevation =
     config.components?.surface?.elevation ?? DEFAULT_ELEVATION;
   registry.icons = config.icons ?? {};
-  registry.imageComponent = config.image ?? DefaultImage;
+  registry.imageComponent = config.image ?? defaultImage;
 
   registry.accents = {};
   for (const [name, accent] of Object.entries(config.accents ?? {})) {

package/src/theme/runtime.ts

@@ -1,6 +1,6 @@
 import { UnistylesRuntime } from 'react-native-unistyles';
 
-import { getRegistry, resolveTheme } from './configure';
+import { getRegistry, resolveTheme } from './registry';
 import type { Scheme } from './types';
 
 /** Apply a named accent at runtime by updating both registered themes. */