@ankhorage/surface 1.0.3 → 1.2.0

package/src/components/navigation/types.ts

@@ -0,0 +1,59 @@
+import type React from 'react';
+import type { AccessibilityRole, AccessibilityState } from 'react-native';
+
+import type { IconProps } from '../../primitives/icon';
+
+export type NavigationItemIcon = Pick<IconProps, 'name' | 'provider'>;
+
+export interface NavigationItemSpec {
+  id: string;
+  label: React.ReactNode;
+  icon?: NavigationItemIcon;
+  badge?: React.ReactNode;
+  active?: boolean;
+  disabled?: boolean;
+  onPress?: (() => void) | undefined;
+  accessibilityLabel?: string;
+  accessibilityRole?: AccessibilityRole;
+  accessibilityState?: AccessibilityState;
+  testID?: string;
+}
+
+export interface NavigationItemProps {
+  item: NavigationItemSpec;
+  compact?: boolean;
+  testID?: string;
+}
+
+export interface NavigationListProps {
+  items: readonly NavigationItemSpec[];
+  orientation?: 'vertical' | 'horizontal';
+  compact?: boolean;
+  testID?: string;
+}
+
+export interface TabBarProps {
+  items: readonly NavigationItemSpec[];
+  compact?: boolean;
+  testID?: string;
+}
+
+export interface TabBarItemProps {
+  item: NavigationItemSpec;
+  compact?: boolean;
+  testID?: string;
+}
+
+export interface DrawerNavigationProps {
+  items: readonly NavigationItemSpec[];
+  header?: React.ReactNode;
+  footer?: React.ReactNode;
+  compact?: boolean;
+  testID?: string;
+}
+
+export interface DrawerNavigationItemProps {
+  item: NavigationItemSpec;
+  compact?: boolean;
+  testID?: string;
+}

package/src/index.test.ts

@@ -21,6 +21,7 @@ const expectedRootExports = [
   "export { IconButton } from './components/icon-button';",
   "export { Label } from './components/label';",
   "export { ListItem } from './components/list-item';",
+  "export {\n  DrawerNavigation,\n  DrawerNavigationItem,\n  NavigationItem,\n  NavigationList,\n  TabBar,\n  TabBarItem,\n} from './components/navigation';",
   "export { Menu } from './components/menu';",
   "export { Modal } from './components/modal';",
   "export { Radio } from './components/radio';",
@@ -32,6 +33,7 @@ const expectedRootExports = [
   "export { Tooltip } from './components/tooltip';",
   "export * from './core/responsive';",
   "export * from './layout';",
+  "export { Image } from './primitives/image';",
   "export * from './theme';",
 ] as const;
 

package/src/index.ts

@@ -22,6 +22,24 @@ export type { MenuItem, MenuProps } from './components/menu';
 export { Menu } from './components/menu';
 export type { ModalProps } from './components/modal';
 export { Modal } from './components/modal';
+export type {
+  DrawerNavigationItemProps,
+  DrawerNavigationProps,
+  NavigationItemIcon,
+  NavigationItemProps,
+  NavigationItemSpec,
+  NavigationListProps,
+  TabBarItemProps,
+  TabBarProps,
+} from './components/navigation';
+export {
+  DrawerNavigation,
+  DrawerNavigationItem,
+  NavigationItem,
+  NavigationList,
+  TabBar,
+  TabBarItem,
+} from './components/navigation';
 export type { RadioProps } from './components/radio';
 export { Radio } from './components/radio';
 export type { SwitchProps } from './components/switch';
@@ -48,6 +66,8 @@ export type { HeadingLevel, HeadingProps } from './primitives/heading';
 export { Heading } from './primitives/heading';
 export type { IconProps, IconProvider } from './primitives/icon';
 export { Icon } from './primitives/icon';
+export type { ImageFit, ImageProps, SurfaceImageSource } from './primitives/image';
+export { Image } from './primitives/image';
 export type { TextProps } from './primitives/text';
 export { Text } from './primitives/text';
 export * from './theme';

package/src/primitives/image/Image.tsx

@@ -0,0 +1,68 @@
+import React from 'react';
+import { Image as RNImage } from 'react-native';
+
+import { useTheme } from '../../theme/ThemeContext';
+import {
+  getSourceKey,
+  normalizeSource,
+  resolveAccessibilityLabel,
+  resolveAlt,
+  resolveImageStyle,
+  resolveRenderedSource,
+  resolveResizeMode,
+} from './resolveImageProps';
+import type { ImageProps } from './types';
+
+export function Image({
+  source,
+  fallbackSource,
+  alt,
+  accessibilityLabel,
+  width,
+  height,
+  aspectRatio,
+  fit,
+  resizeMode,
+  radius,
+  style,
+  testID,
+  onError,
+}: ImageProps) {
+  const { theme } = useTheme();
+  const [showFallback, setShowFallback] = React.useState(false);
+  const primaryKey = React.useMemo(() => getSourceKey(source), [source]);
+
+  React.useEffect(() => {
+    setShowFallback(false);
+  }, [primaryKey]);
+
+  const normalizedPrimary = normalizeSource(source);
+  const normalizedFallback = normalizeSource(fallbackSource);
+  const resolvedSource = resolveRenderedSource(normalizedPrimary, normalizedFallback, showFallback);
+
+  if (!resolvedSource) return null;
+
+  const resolvedResizeMode = resolveResizeMode(fit, resizeMode);
+  const resolvedAccessibilityLabel = resolveAccessibilityLabel(alt, accessibilityLabel);
+  const resolvedAlt = resolveAlt(alt, accessibilityLabel);
+  const resolvedStyle = resolveImageStyle(theme, { width, height, aspectRatio, radius });
+
+  return (
+    <RNImage
+      accessibilityLabel={resolvedAccessibilityLabel}
+      accessibilityRole="image"
+      alt={resolvedAlt}
+      onError={(event) => {
+        onError?.(event);
+
+        if (!showFallback && normalizedFallback) {
+          setShowFallback(true);
+        }
+      }}
+      resizeMode={resolvedResizeMode}
+      source={resolvedSource}
+      style={[resolvedStyle, style]}
+      testID={testID}
+    />
+  );
+}

package/src/primitives/image/index.ts

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

package/src/primitives/image/resolveImageProps.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import {
+  getSourceKey,
+  normalizeSource,
+  resolveImageStyle,
+  resolveRenderedSource,
+  resolveResizeMode,
+} from './resolveImageProps';
+
+describe('normalizeSource', () => {
+  it('normalizes string sources into uri objects', () => {
+    expect(normalizeSource('https://example.com/image.png')).toEqual({
+      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();
+  });
+});
+
+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');
+  });
+});
+
+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);
+  });
+});
+
+describe('getSourceKey', () => {
+  it('derives stable keys for string and uri sources', () => {
+    expect(getSourceKey('https://example.com/image.png')).toBe('uri:https://example.com/image.png');
+    expect(getSourceKey({ uri: 'https://example.com/image.png' })).toBe(
+      'uri:https://example.com/image.png',
+    );
+  });
+
+  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', () => {
+    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/primitives/image/resolveImageProps.ts

@@ -0,0 +1,92 @@
+import type { ImageResizeMode, ImageSourcePropType } from 'react-native';
+import type { ImageStyle } from 'react-native';
+
+import { resolveToken } from '../../theme/resolveToken';
+import type { SurfaceTheme } from '../../theme/types';
+import type { ImageProps, SurfaceImageSource } from './types';
+
+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;
+}
+
+export function resolveRenderedSource(
+  normalizedPrimary: ImageSourcePropType | undefined,
+  normalizedFallback: ImageSourcePropType | undefined,
+  showFallback: boolean,
+): ImageSourcePropType | undefined {
+  if (showFallback || !normalizedPrimary) return normalizedFallback;
+  return normalizedPrimary;
+}
+
+function getUriFromSource(source: ImageSourcePropType): string | undefined {
+  if (Array.isArray(source)) {
+    const [first] = source;
+    return first?.uri;
+  }
+
+  if (typeof source === 'number') return undefined;
+  return source.uri;
+}
+
+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';
+  }
+}
+
+export function resolveResizeMode(
+  fit: ImageProps['fit'],
+  resizeMode: ImageProps['resizeMode'],
+): ImageResizeMode {
+  return fit ?? resizeMode ?? 'cover';
+}
+
+export function resolveAccessibilityLabel(
+  alt: ImageProps['alt'],
+  accessibilityLabel: ImageProps['accessibilityLabel'],
+): string | undefined {
+  return accessibilityLabel ?? alt;
+}
+
+export function resolveAlt(
+  alt: ImageProps['alt'],
+  accessibilityLabel: ImageProps['accessibilityLabel'],
+): string | undefined {
+  return alt ?? accessibilityLabel;
+}
+
+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/primitives/image/types.ts

@@ -0,0 +1,28 @@
+import type {
+  ImageProps as ReactNativeImageProps,
+  ImageResizeMode,
+  ImageSourcePropType,
+} from 'react-native';
+import type { ImageStyle, StyleProp } from 'react-native';
+
+import type { SurfaceTheme } from '../../theme/types';
+
+export type SurfaceImageSource = string | ImageSourcePropType;
+
+export type ImageFit = ImageResizeMode;
+
+export interface ImageProps {
+  source?: SurfaceImageSource | null;
+  fallbackSource?: SurfaceImageSource | null;
+  alt?: string;
+  accessibilityLabel?: string;
+  width?: number | string;
+  height?: number | string;
+  aspectRatio?: number;
+  fit?: ImageFit;
+  resizeMode?: ImageResizeMode;
+  radius?: number | keyof SurfaceTheme['radii'];
+  style?: StyleProp<ImageStyle>;
+  testID?: string;
+  onError?: ReactNativeImageProps['onError'];
+}