@ankhorage/surface 4.2.0 → 4.3.0

package/src/features/icon/constants.ts

@@ -0,0 +1,9 @@
+import type { IconProvider } from '../../types/icon';
+
+export const SUPPORTED_ICON_PROVIDERS = [
+  'Ionicons',
+  'FontAwesome',
+  'FontAwesome5',
+  'FontAwesome6',
+  'MaterialDesignIcons',
+] as const satisfies readonly IconProvider[];

package/src/features/icon/public.ts

@@ -0,0 +1,10 @@
+export type {
+  FontIconSource,
+  IconProps,
+  IconProvider,
+  IconSource,
+  IconVariant,
+  SvgIconSource,
+} from '../../types/icon';
+export { Icon } from './adapters/inbound/Icon';
+export { SUPPORTED_ICON_PROVIDERS } from './constants';

package/src/features/image/adapters/inbound/Image.tsx

@@ -0,0 +1,55 @@
+import React from 'react';
+import { Image as ReactNativeImage } from 'react-native';
+
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { ImageProps } from '../../../../types/image';
+import { getSourceKey } from '../../utils/getSourceKey';
+import { normalizeSource } from '../../utils/normalizeSource';
+import { resolveAccessibilityLabel } from '../../utils/resolveAccessibilityLabel';
+import { resolveAlt } from '../../utils/resolveAlt';
+import { resolveImageStyle } from '../../utils/resolveImageStyle';
+import { resolveRenderedSource } from '../../utils/resolveRenderedSource';
+import { resolveResizeMode } from '../../utils/resolveResizeMode';
+
+/*** Renders a token-aware accessible image with optional fallback source. */
+export function Image({
+  source,
+  fallbackSource,
+  alt,
+  accessibilityLabel,
+  width,
+  height,
+  aspectRatio,
+  fit,
+  resizeMode,
+  radius,
+  style,
+  testID,
+  onError,
+}: ImageProps) {
+  const { theme } = useTheme();
+  const primaryKey = React.useMemo(() => getSourceKey(source), [source]);
+  const [failedPrimaryKey, setFailedPrimaryKey] = React.useState<string | null>(null);
+  const showFallback = primaryKey !== null && failedPrimaryKey === primaryKey;
+  const normalizedPrimary = normalizeSource(source);
+  const normalizedFallback = normalizeSource(fallbackSource);
+  const resolvedSource = resolveRenderedSource(normalizedPrimary, normalizedFallback, showFallback);
+
+  if (!resolvedSource) return null;
+
+  return (
+    <ReactNativeImage
+      accessibilityLabel={resolveAccessibilityLabel(alt, accessibilityLabel)}
+      accessibilityRole="image"
+      alt={resolveAlt(alt, accessibilityLabel)}
+      onError={(event) => {
+        onError?.(event);
+        if (!showFallback && normalizedFallback) setFailedPrimaryKey(primaryKey);
+      }}
+      resizeMode={resolveResizeMode(fit, resizeMode)}
+      source={resolvedSource}
+      style={[resolveImageStyle(theme, { width, height, aspectRatio, radius }), style]}
+      testID={testID}
+    />
+  );
+}

package/src/features/image/public.ts

@@ -0,0 +1,2 @@
+export type { ImageFit, ImageProps, SurfaceImageSource } from '../../types/image';
+export { Image } from './adapters/inbound/Image';

package/src/features/image/utils/getSourceKey.ts

@@ -0,0 +1,32 @@
+import type { ImageSourcePropType } from 'react-native';
+
+import type { SurfaceImageSource } from '../../../types/image';
+
+/*** Derives a stable runtime key for one Surface image source. */
+export function getSourceKey(source: SurfaceImageSource | null | undefined): string | null {
+  if (source === null || source === undefined) return null;
+  if (typeof source === 'string') return `uri:${source}`;
+  if (typeof source === 'number') return `asset:${source}`;
+  if (Array.isArray(source)) {
+    const parts = source
+      .map((item) => item.uri)
+      .filter((value): value is string => typeof value === 'string');
+    return `uri-set:${parts.join('|')}`;
+  }
+
+  const uri = getUriFromSource(source);
+  if (uri) return `uri:${uri}`;
+
+  try {
+    return `src:${JSON.stringify(source)}`;
+  } catch {
+    return 'src:unknown';
+  }
+}
+
+/*** Reads the first URI represented by a React Native image source. */
+function getUriFromSource(source: ImageSourcePropType): string | undefined {
+  if (Array.isArray(source)) return source[0]?.uri;
+  if (typeof source === 'number') return undefined;
+  return source.uri;
+}

package/src/features/image/utils/normalizeSource.ts

@@ -0,0 +1,12 @@
+import type { ImageSourcePropType } from 'react-native';
+
+import type { SurfaceImageSource } from '../../../types/image';
+
+/*** Normalizes a Surface image source into React Native's source shape. */
+export function normalizeSource(
+  source: SurfaceImageSource | null | undefined,
+): ImageSourcePropType | undefined {
+  if (source === null || source === undefined) return undefined;
+  if (typeof source === 'string') return { uri: source };
+  return source;
+}

package/src/features/image/utils/resolveAccessibilityLabel.ts

@@ -0,0 +1,9 @@
+import type { ImageProps } from '../../../types/image';
+
+/*** Resolves the accessible image label from explicit label or alt text. */
+export function resolveAccessibilityLabel(
+  alt: ImageProps['alt'],
+  accessibilityLabel: ImageProps['accessibilityLabel'],
+): string | undefined {
+  return accessibilityLabel ?? alt;
+}

package/src/features/image/utils/resolveAlt.ts

@@ -0,0 +1,9 @@
+import type { ImageProps } from '../../../types/image';
+
+/*** Resolves web alt text from alt or the accessible label. */
+export function resolveAlt(
+  alt: ImageProps['alt'],
+  accessibilityLabel: ImageProps['accessibilityLabel'],
+): string | undefined {
+  return alt ?? accessibilityLabel;
+}

package/src/{primitives/image → features/image/utils}/resolveImageProps.test.ts

@@ -1,13 +1,11 @@
 import { describe, expect, it } from 'bun:test';
 
-import { createTheme } from '../../theme/createTheme';
-import {
-  getSourceKey,
-  normalizeSource,
-  resolveImageStyle,
-  resolveRenderedSource,
-  resolveResizeMode,
-} from './resolveImageProps';
+import { createTheme } from '../../../theme/createTheme';
+import { getSourceKey } from './getSourceKey';
+import { normalizeSource } from './normalizeSource';
+import { resolveImageStyle } from './resolveImageStyle';
+import { resolveRenderedSource } from './resolveRenderedSource';
+import { resolveResizeMode } from './resolveResizeMode';
 
 describe('normalizeSource', () => {
   it('normalizes string sources into uri objects', () => {
@@ -15,13 +13,11 @@ describe('normalizeSource', () => {
       uri: 'https://example.com/image.png',
     });
   });
-
   it('passes through react-native image sources', () => {
     expect(normalizeSource({ uri: 'https://example.com/image.png' })).toEqual({
       uri: 'https://example.com/image.png',
     });
   });
-
   it('returns undefined for nullish sources', () => {
     expect(normalizeSource(null)).toBeUndefined();
     expect(normalizeSource(undefined)).toBeUndefined();
@@ -32,7 +28,6 @@ describe('resolveResizeMode', () => {
   it('prefers fit over resizeMode', () => {
     expect(resolveResizeMode('contain', 'cover')).toBe('contain');
   });
-
   it('defaults to cover when both are absent', () => {
     expect(resolveResizeMode(undefined, undefined)).toBe('cover');
   });
@@ -40,8 +35,8 @@ describe('resolveResizeMode', () => {
 
 describe('resolveRenderedSource', () => {
   it('renders fallback when the primary source is absent', () => {
-    const normalizedFallback = normalizeSource('https://example.com/fallback.png');
-    expect(resolveRenderedSource(undefined, normalizedFallback, false)).toEqual(normalizedFallback);
+    const fallback = normalizeSource('https://example.com/fallback.png');
+    expect(resolveRenderedSource(undefined, fallback, false)).toEqual(fallback);
   });
 });
 
@@ -52,29 +47,22 @@ describe('getSourceKey', () => {
       'uri:https://example.com/image.png',
     );
   });
-
-  it('derives stable keys for asset sources', () => {
-    expect(getSourceKey(12)).toBe('asset:12');
-  });
-
+  it('derives stable keys for asset sources', () => expect(getSourceKey(12)).toBe('asset:12'));
   it('derives stable keys for uri sets', () => {
     expect(getSourceKey([{ uri: 'a' }, { uri: 'b' }])).toBe('uri-set:a|b');
   });
 });
 
 describe('resolveImageStyle', () => {
-  it('resolves spacing tokens for width/height and preserves raw strings', () => {
+  it('resolves spacing tokens for dimensions and preserves raw strings', () => {
     const theme = createTheme();
     const style = resolveImageStyle(theme, { width: 'm', height: '100%' });
-
     expect(style.width).toBe(theme.spacing.m);
     expect(style.height).toBe('100%');
   });
-
   it('resolves radius tokens for borderRadius', () => {
     const theme = createTheme();
     const style = resolveImageStyle(theme, { radius: 'full' });
-
     expect(style.borderRadius).toBe(theme.radii.full);
     expect(style.overflow).toBe('hidden');
   });

package/src/features/image/utils/resolveImageStyle.ts

@@ -0,0 +1,23 @@
+import type { ImageStyle } from 'react-native';
+
+import { resolveToken } from '../../../theme/resolveToken';
+import type { SurfaceTheme } from '../../../theme/types';
+import type { ImageProps } from '../../../types/image';
+
+/*** Resolves token-aware dimensions and radius for a Surface image. */
+export function resolveImageStyle(
+  theme: SurfaceTheme,
+  props: Pick<ImageProps, 'width' | 'height' | 'aspectRatio' | 'radius'>,
+): ImageStyle {
+  const width = resolveToken(theme.spacing, props.width);
+  const height = resolveToken(theme.spacing, props.height);
+  const borderRadius = resolveToken(theme.radii, props.radius);
+
+  return {
+    width,
+    height,
+    aspectRatio: props.aspectRatio,
+    borderRadius,
+    overflow: borderRadius !== undefined ? 'hidden' : undefined,
+  };
+}

package/src/features/image/utils/resolveRenderedSource.ts

@@ -0,0 +1,11 @@
+import type { ImageSourcePropType } from 'react-native';
+
+/*** Chooses the primary or fallback normalized image source. */
+export function resolveRenderedSource(
+  normalizedPrimary: ImageSourcePropType | undefined,
+  normalizedFallback: ImageSourcePropType | undefined,
+  showFallback: boolean,
+): ImageSourcePropType | undefined {
+  if (showFallback || !normalizedPrimary) return normalizedFallback;
+  return normalizedPrimary;
+}

package/src/features/image/utils/resolveResizeMode.ts

@@ -0,0 +1,11 @@
+import type { ImageResizeMode } from 'react-native';
+
+import type { ImageProps } from '../../../types/image';
+
+/*** Resolves the canonical resize mode, preferring the Surface fit alias. */
+export function resolveResizeMode(
+  fit: ImageProps['fit'],
+  resizeMode: ImageProps['resizeMode'],
+): ImageResizeMode {
+  return fit ?? resizeMode ?? 'cover';
+}

package/src/features/keyboard-avoiding-view/adapters/inbound/KeyboardAvoidingView.tsx

@@ -0,0 +1,9 @@
+import React from 'react';
+import { KeyboardAvoidingView as ReactNativeKeyboardAvoidingView } from 'react-native';
+
+import type { KeyboardAvoidingViewProps } from '../../../../types/keyboard-avoiding-view';
+
+/*** Preserves React Native keyboard avoidance behind the stable Surface feature boundary. */
+export function KeyboardAvoidingView(props: KeyboardAvoidingViewProps) {
+  return <ReactNativeKeyboardAvoidingView {...props} />;
+}

package/src/features/keyboard-avoiding-view/public.ts

@@ -0,0 +1,5 @@
+export type {
+  KeyboardAvoidingViewBehavior,
+  KeyboardAvoidingViewProps,
+} from '../../types/keyboard-avoiding-view';
+export { KeyboardAvoidingView } from './adapters/inbound/KeyboardAvoidingView';

package/src/{layout → features/layout/adapters/inbound}/Box.tsx

@@ -1,21 +1,13 @@
 import React from 'react';
-import { View, type ViewProps as ReactNativeViewProps } from 'react-native';
+import { View } from 'react-native';
 
-import { useResponsiveRuntime } from '../core/responsive';
-import { resolvePointerEvents } from '../internal/resolvePointerEvents';
-import { useTheme } from '../theme/ThemeContext';
-import { type BoxStyleProps, resolveBoxStyles } from './helpers';
-
-export interface BoxProps extends BoxStyleProps {
-  accessibilityLabel?: ReactNativeViewProps['accessibilityLabel'];
-  accessibilityRole?: ReactNativeViewProps['accessibilityRole'];
-  accessibilityState?: ReactNativeViewProps['accessibilityState'];
-  accessible?: ReactNativeViewProps['accessible'];
-  children?: React.ReactNode;
-  pointerEvents?: ReactNativeViewProps['pointerEvents'];
-  testID?: string;
-}
+import { useResponsiveRuntime } from '../../../../core/responsive';
+import { resolvePointerEvents } from '../../../../internal/resolvePointerEvents';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { BoxProps } from '../../../../types/layout';
+import { resolveBoxStyles } from '../../../../utils/resolveBoxStyles';
 
+/*** Renders the responsive foundational layout box. */
 export function Box({
   accessible,
   accessibilityLabel,

package/src/features/layout/adapters/inbound/Container.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import { StyleSheet, View, type ViewStyle } from 'react-native';
+
+import { resolveResponsive, useResponsiveRuntime } from '../../../../core/responsive';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { ContainerProps } from '../../../../types/layout';
+import { resolveSpacing } from '../../../../utils/resolveSpacing';
+import { Box } from './Box';
+
+/*** Centers responsive content inside a configurable maximum width. */
+export function Container({
+  children,
+  maxWidth = { base: Number.MAX_SAFE_INTEGER, lg: 1120 },
+  px = { base: 16, md: 24, lg: 32 },
+  ...props
+}: ContainerProps) {
+  const { theme } = useTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const activeMaxWidth = resolveResponsive(maxWidth, breakpoint);
+  const activePx = resolveSpacing(theme, resolveResponsive(px, breakpoint));
+
+  return (
+    <Box {...props} width="100%" style={[styles.fullWidth, props.style]}>
+      <View style={resolveContainerStyle(activeMaxWidth, activePx)}>{children}</View>
+    </Box>
+  );
+}
+
+/*** Resolves centered responsive Container dimensions and padding. */
+function resolveContainerStyle(
+  maxWidth: number | undefined,
+  horizontalPadding: number | undefined,
+): ViewStyle {
+  return {
+    alignSelf: 'center',
+    maxWidth,
+    paddingLeft: horizontalPadding,
+    paddingRight: horizontalPadding,
+    width: '100%',
+  };
+}
+
+const styles = StyleSheet.create({ fullWidth: { width: '100%' } });

package/src/{layout → features/layout/adapters/inbound}/Divider.tsx

@@ -1,14 +1,9 @@
 import React from 'react';
 
-import { Box, type BoxProps } from './Box';
-import type { ColorValue } from './helpers';
-
-export interface DividerProps extends Omit<BoxProps, 'bg' | 'height' | 'width'> {
-  orientation?: 'horizontal' | 'vertical';
-  color?: ColorValue;
-  thickness?: number;
-}
+import type { DividerProps } from '../../../../types/layout';
+import { Box } from './Box';
 
+/*** Renders a horizontal or vertical separator using layout tokens. */
 export function Divider({
   orientation = 'horizontal',
   color = 'border',

package/src/features/layout/adapters/inbound/Grid.tsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import { View, type ViewStyle } from 'react-native';
+
+import { resolveResponsive, useResponsiveRuntime } from '../../../../core/responsive';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { GridProps } from '../../../../types/layout';
+import { resolveSpacing } from '../../../../utils/resolveSpacing';
+import { Box } from './Box';
+
+/*** Lays out children in a responsive wrapping grid. */
+export function Grid({
+  children,
+  cols,
+  gap = 0,
+  rowGap,
+  colGap,
+  minItemWidth,
+  ...props
+}: GridProps) {
+  const { theme } = useTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const activeCols = Math.max(1, Math.floor(resolveResponsive(cols, breakpoint) ?? 1));
+  const defaultGap = resolveResponsive(gap, breakpoint) ?? 0;
+  const rowSpacing = Number(
+    resolveSpacing(theme, resolveResponsive(rowGap, breakpoint) ?? defaultGap) ?? 0,
+  );
+  const colSpacing = Number(
+    resolveSpacing(theme, resolveResponsive(colGap, breakpoint) ?? defaultGap) ?? 0,
+  );
+  const activeMinItemWidth = resolveResponsive(minItemWidth, breakpoint);
+  const basisPercent: `${number}%` = `${100 / activeCols}%`;
+
+  return (
+    <Box {...props}>
+      <View style={resolveGridStyle(rowSpacing, colSpacing)}>
+        {React.Children.toArray(children).map((node, index) => (
+          <View
+            key={String(index)}
+            style={resolveGridItemStyle(activeMinItemWidth, basisPercent, rowSpacing, colSpacing)}
+          >
+            {node}
+          </View>
+        ))}
+      </View>
+    </Box>
+  );
+}
+
+/*** Resolves the wrapping Grid container style. */
+function resolveGridStyle(rowSpacing: number, colSpacing: number): ViewStyle {
+  return {
+    flexDirection: 'row',
+    flexWrap: 'wrap',
+    marginLeft: -colSpacing / 2,
+    marginRight: -colSpacing / 2,
+    marginTop: -rowSpacing / 2,
+  };
+}
+
+/*** Resolves a fixed-column or minimum-width grid item style. */
+function resolveGridItemStyle(
+  minItemWidth: number | undefined,
+  basisPercent: `${number}%`,
+  rowSpacing: number,
+  colSpacing: number,
+): ViewStyle {
+  const sizing =
+    minItemWidth === undefined
+      ? { width: basisPercent, flexBasis: basisPercent }
+      : { minWidth: minItemWidth, flexBasis: minItemWidth, flexGrow: 1 };
+  return {
+    ...sizing,
+    paddingBottom: rowSpacing / 2,
+    paddingLeft: colSpacing / 2,
+    paddingRight: colSpacing / 2,
+    paddingTop: rowSpacing / 2,
+  };
+}

package/src/{layout → features/layout/adapters/inbound}/Stack.test.ts

@@ -5,7 +5,6 @@ import { describe, expect, it } from 'bun:test';
 describe('Stack layout contract', () => {
   it('keeps authored children as direct flex items and applies spacing through gap', async () => {
     const source = await readFile(new URL('./Stack.tsx', import.meta.url), 'utf8');
-
     expect(source).toContain('gap: activeGap');
     expect(source).toContain('{children}');
     expect(source).not.toContain("from 'react-native'");

package/src/{layout → features/layout/adapters/inbound}/Stack.tsx

@@ -1,21 +1,12 @@
 import type React from 'react';
 
-import { resolveResponsive, type Responsive, useResponsiveRuntime } from '../core/responsive';
-import { useTheme } from '../theme/ThemeContext';
-import { Box, type BoxProps } from './Box';
-import { resolveSpacing, type SpaceValue } from './helpers';
-
-export interface StackProps extends Omit<BoxProps, 'children'> {
-  children?: React.ReactNode;
-  direction?: Responsive<'row' | 'column'>;
-  gap?: Responsive<SpaceValue>;
-  align?: Responsive<'flex-start' | 'center' | 'flex-end' | 'stretch' | 'baseline'>;
-  justify?: Responsive<
-    'flex-start' | 'center' | 'flex-end' | 'space-between' | 'space-around' | 'space-evenly'
-  >;
-  wrap?: Responsive<'nowrap' | 'wrap'>;
-}
+import { resolveResponsive, useResponsiveRuntime } from '../../../../core/responsive';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { StackProps } from '../../../../types/layout';
+import { resolveSpacing } from '../../../../utils/resolveSpacing';
+import { Box } from './Box';
 
+/*** Stacks authored children directly along a responsive flex direction. */
 export function Stack({
   children,
   direction = 'column',

package/src/features/layout/public.ts

@@ -0,0 +1,12 @@
+export type {
+  BoxProps,
+  ContainerProps,
+  DividerProps,
+  GridProps,
+  StackProps,
+} from '../../types/layout';
+export { Box } from './adapters/inbound/Box';
+export { Container } from './adapters/inbound/Container';
+export { Divider } from './adapters/inbound/Divider';
+export { Grid } from './adapters/inbound/Grid';
+export { Stack } from './adapters/inbound/Stack';

package/src/{layout → features/surface/adapters/inbound}/Surface.tsx

@@ -1,15 +1,31 @@
 import React from 'react';
 import type { ViewStyle } from 'react-native';
 
-import { useTheme } from '../theme/ThemeContext';
-import { Box, type BoxProps } from './Box';
+import { useTheme } from '../../../../theme/ThemeContext';
+import type { SurfaceProps, SurfaceVariant } from '../../../../types/surface';
+import { Box } from '../../../layout/public';
 
-export type SurfaceVariant = 'default' | 'subtle' | 'raised' | 'outline';
+/*** Renders a themed container surface with semantic elevation and border variants. */
+export function Surface({ variant = 'default', radius = 'm', style, ...props }: SurfaceProps) {
+  const { theme } = useTheme();
+  const backgroundColor =
+    variant === 'subtle'
+      ? theme.semantics.surface.subtle
+      : variant === 'raised'
+        ? theme.semantics.surface.raised
+        : theme.semantics.surface.default;
+  const borderColor = theme.semantics.border.default;
 
-export interface SurfaceProps extends Omit<BoxProps, 'bg' | 'borderColor' | 'borderWidth'> {
-  variant?: SurfaceVariant;
+  return (
+    <Box
+      {...props}
+      radius={radius}
+      style={[resolveSurfaceVariantStyles(variant, borderColor, backgroundColor), style]}
+    />
+  );
 }
 
+/*** Resolves the semantic visual treatment for one Surface variant. */
 function resolveSurfaceVariantStyles(
   variant: SurfaceVariant,
   borderColor: string,
@@ -17,11 +33,7 @@ function resolveSurfaceVariantStyles(
 ): ViewStyle {
   switch (variant) {
     case 'subtle':
-      return {
-        backgroundColor,
-        borderColor: 'transparent',
-        borderWidth: 0,
-      };
+      return { backgroundColor, borderColor: 'transparent', borderWidth: 0 };
     case 'raised':
       return {
         backgroundColor,
@@ -34,37 +46,8 @@ function resolveSurfaceVariantStyles(
         shadowRadius: 8,
       };
     case 'outline':
-      return {
-        backgroundColor: 'transparent',
-        borderColor,
-        borderWidth: 1,
-      };
+      return { backgroundColor: 'transparent', borderColor, borderWidth: 1 };
     case 'default':
-    default:
-      return {
-        backgroundColor,
-        borderColor,
-        borderWidth: 1,
-      };
+      return { backgroundColor, borderColor, borderWidth: 1 };
   }
 }
-
-export function Surface({ variant = 'default', radius = 'm', style, ...props }: SurfaceProps) {
-  const { theme } = useTheme();
-
-  const backgroundColor =
-    variant === 'subtle'
-      ? theme.semantics.surface.subtle
-      : variant === 'raised'
-        ? theme.semantics.surface.raised
-        : theme.semantics.surface.default;
-  const borderColor = theme.semantics.border.default;
-
-  return (
-    <Box
-      {...props}
-      radius={radius}
-      style={[resolveSurfaceVariantStyles(variant, borderColor, backgroundColor), style]}
-    />
-  );
-}

package/src/features/surface/public.ts

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