@ankhorage/surface 1.3.1 → 2.0.0

package/src/components/toast/types.ts

@@ -1,11 +1,13 @@
 import type React from 'react';
 
-export type ToastTone = 'default' | 'success' | 'danger';
+import type { SurfaceStatusColor } from '../../surfaceColor';
+
+export type ToastStatus = 'default' | SurfaceStatusColor;
 
 export interface ToastProps {
   title?: React.ReactNode;
   description?: React.ReactNode;
-  tone?: ToastTone;
+  status?: ToastStatus;
   onDismiss?: (() => void) | undefined;
   testID?: string;
 }

package/src/components/tooltip/Tooltip.tsx

@@ -98,7 +98,7 @@ export function Tooltip({
             testID={testID}
             variant="raised"
           >
-            <Text color={theme.semantics.content.inverse} variant="caption">
+            <Text emphasis="inverse" variant="caption">
               {content}
             </Text>
           </Surface>

package/src/examples/DocsExamples.tsx

@@ -42,8 +42,8 @@ export function ProviderExample() {
     <ThemeProvider initialConfig={docsThemeConfig}>
       <Stack gap="m" p="l">
         <Text variant="body">Surface starter</Text>
-        <Badge content="Foundation" tone="success" />
-        <Button tone="warning" variant="soft">
+        <Badge color="success" content="Foundation" />
+        <Button color="warning" variant="soft">
           Continue
         </Button>
       </Stack>
@@ -66,7 +66,7 @@ export function FormAndOverlayExample() {
           <Checkbox defaultChecked>Weekly updates</Checkbox>
           <Radio>Product announcements</Radio>
           <Switch readOnly>Read-only setting</Switch>
-          <HelperText tone="danger">Invalid fields should reuse the same danger tone.</HelperText>
+          <HelperText color="error">Invalid fields should reuse the same error color.</HelperText>
         </Stack>
         <Modal visible={false}>
           <Text>Modal content</Text>
@@ -106,7 +106,7 @@ export function NavigationExample() {
           trigger={<Text>Open menu</Text>}
         />
         <Box>
-          <Text tone="success">Theme overrides can stay semantic.</Text>
+          <Text color="success">Theme overrides can stay semantic.</Text>
         </Box>
       </Stack>
     </ThemeProvider>

package/src/index.test.ts

@@ -34,6 +34,7 @@ const expectedRootExports = [
   "export * from './core/responsive';",
   "export * from './layout';",
   "export { Image } from './primitives/image';",
+  "export {\n  SURFACE_COLORS,\n  SURFACE_EMPHASES,\n  SURFACE_PALETTE_COLORS,\n  SURFACE_STATUS_COLORS,\n} from './surfaceColor';",
   "export * from './theme';",
 ] as const;
 

package/src/index.ts

@@ -50,7 +50,7 @@ export type { TextInputProps } from './components/text-input';
 export { TextInput } from './components/text-input';
 export type { TextareaProps } from './components/textarea';
 export { Textarea } from './components/textarea';
-export type { ToastOptions, ToastProps, ToastTone } from './components/toast';
+export type { ToastOptions, ToastProps, ToastStatus } from './components/toast';
 export { Toast, ToastProvider, useToast } from './components/toast';
 export type { TooltipProps } from './components/tooltip';
 export { Tooltip } from './components/tooltip';
@@ -70,6 +70,18 @@ export type { ImageFit, ImageProps, SurfaceImageSource } from './primitives/imag
 export { Image } from './primitives/image';
 export type { TextProps } from './primitives/text';
 export { Text } from './primitives/text';
+export type {
+  SurfaceColor,
+  SurfaceEmphasis,
+  SurfacePaletteColor,
+  SurfaceStatusColor,
+} from './surfaceColor';
+export {
+  SURFACE_COLORS,
+  SURFACE_EMPHASES,
+  SURFACE_PALETTE_COLORS,
+  SURFACE_STATUS_COLORS,
+} from './surfaceColor';
 export * from './theme';
 export { isDeepEqual } from './utils/deepEqual';
 export { deepMerge } from './utils/deepMerge';

package/src/internal/resolvers/index.ts

@@ -10,6 +10,6 @@ export * from './resolveOverlayAnimation';
 export * from './resolveOverlayZIndex';
 export * from './resolveSelectionControlBehavior';
 export * from './resolveSelectionControlColors';
+export * from './resolveSurfaceColor';
 export * from './resolveTextColor';
 export * from './resolveTextStyles';
-export * from './resolveTone';

package/src/internal/resolvers/resolveFieldPresentation.test.ts

@@ -4,28 +4,30 @@ import { resolveFieldPresentation } from './resolveFieldPresentation';
 import { resolveFieldState } from './resolveFieldState';
 
 describe('resolveFieldPresentation', () => {
-  it('keeps label and helper tones aligned for default fields', () => {
+  it('keeps label and helper text presentation aligned for default fields', () => {
     expect(resolveFieldPresentation(resolveFieldState({}))).toEqual({
-      helperTone: 'default',
-      labelTone: 'default',
+      helperEmphasis: 'default',
+      labelEmphasis: 'default',
     });
   });
 
   it('mutes both label and helper text for disabled and read-only fields', () => {
     expect(resolveFieldPresentation(resolveFieldState({ disabled: true }))).toEqual({
-      helperTone: 'muted',
-      labelTone: 'muted',
+      helperEmphasis: 'muted',
+      labelEmphasis: 'muted',
     });
     expect(resolveFieldPresentation(resolveFieldState({ readOnly: true }))).toEqual({
-      helperTone: 'muted',
-      labelTone: 'muted',
+      helperEmphasis: 'muted',
+      labelEmphasis: 'muted',
     });
   });
 
-  it('elevates invalid fields to the danger tone', () => {
+  it('elevates invalid fields to the error color', () => {
     expect(resolveFieldPresentation(resolveFieldState({ invalid: true, readOnly: true }))).toEqual({
-      helperTone: 'danger',
-      labelTone: 'danger',
+      helperColor: 'error',
+      helperEmphasis: 'default',
+      labelColor: 'error',
+      labelEmphasis: 'default',
     });
   });
 });

package/src/internal/resolvers/resolveFieldPresentation.ts

@@ -1,30 +1,32 @@
+import type { SurfaceColor, SurfaceEmphasis } from '../../surfaceColor';
 import type { FieldState } from './resolveFieldState';
-import type { TextTone } from './resolveTextColor';
-
-type FieldPresentationTone = Extract<TextTone, 'default' | 'muted' | 'danger'>;
 
 export interface ResolvedFieldPresentation {
-  helperTone: FieldPresentationTone;
-  labelTone: FieldPresentationTone;
+  helperColor?: Extract<SurfaceColor, 'error'>;
+  helperEmphasis: Extract<SurfaceEmphasis, 'default' | 'muted'>;
+  labelColor?: Extract<SurfaceColor, 'error'>;
+  labelEmphasis: Extract<SurfaceEmphasis, 'default' | 'muted'>;
 }
 
 export function resolveFieldPresentation(fieldState: FieldState): ResolvedFieldPresentation {
   if (fieldState.invalid) {
     return {
-      helperTone: 'danger',
-      labelTone: 'danger',
+      helperColor: 'error',
+      helperEmphasis: 'default',
+      labelColor: 'error',
+      labelEmphasis: 'default',
     };
   }
 
   if (fieldState.disabled || fieldState.readOnly) {
     return {
-      helperTone: 'muted',
-      labelTone: 'muted',
+      helperEmphasis: 'muted',
+      labelEmphasis: 'muted',
     };
   }
 
   return {
-    helperTone: 'default',
-    labelTone: 'default',
+    helperEmphasis: 'default',
+    labelEmphasis: 'default',
   };
 }

package/src/internal/resolvers/resolveInteractiveColors.test.ts

@@ -5,11 +5,11 @@ import { resolveFieldState } from './resolveFieldState';
 import { resolveButtonColors, resolveInputColors } from './resolveInteractiveColors';
 
 describe('resolveInteractiveColors', () => {
-  it('maps button variant, tone, and state through semantic slots', () => {
+  it('maps button variant, color, and state through semantic slots', () => {
     const theme = createTheme();
     const solid = resolveButtonColors(theme, {
       variant: 'solid',
-      tone: 'primary',
+      color: 'primary',
       state: {
         disabled: false,
         focused: false,
@@ -19,7 +19,7 @@ describe('resolveInteractiveColors', () => {
     });
     const outline = resolveButtonColors(theme, {
       variant: 'outline',
-      tone: 'danger',
+      color: 'danger',
       state: {
         disabled: false,
         focused: false,
@@ -50,7 +50,7 @@ describe('resolveInteractiveColors', () => {
       }),
     );
 
-    expect(focusedInvalid.borderColor).toBe(theme.semantics.danger.base);
+    expect(focusedInvalid.borderColor).toBe(theme.semantics.error.base);
     expect(readOnly.backgroundColor).toBe(theme.semantics.surface.subtle);
     expect(readOnly.placeholderColor).toBe(theme.semantics.content.muted);
   });

package/src/internal/resolvers/resolveInteractiveColors.ts

@@ -1,7 +1,8 @@
+import type { SurfaceColor } from '../../surfaceColor';
 import type { SurfaceTheme } from '../../theme/types';
 import type { FieldState } from './resolveFieldState';
 import type { InteractionState } from './resolveInteractiveState';
-import { type ComponentTone, resolveTone } from './resolveTone';
+import { resolveSurfaceColor } from './resolveSurfaceColor';
 
 export type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'soft';
 
@@ -16,11 +17,11 @@ export function resolveButtonColors(
   theme: SurfaceTheme,
   {
     variant,
-    tone,
+    color,
     state,
   }: {
     variant: ButtonVariant;
-    tone: ComponentTone;
+    color: SurfaceColor;
     state: InteractionState;
   },
 ): ResolvedInteractiveColors {
@@ -33,7 +34,7 @@ export function resolveButtonColors(
     };
   }
 
-  const semanticTone = resolveTone(theme, tone);
+  const semanticTone = resolveSurfaceColor(theme, color);
 
   switch (variant) {
     case 'outline':
@@ -99,9 +100,7 @@ export function resolveInputColors(
       backgroundColor: fieldState.readOnly
         ? theme.semantics.surface.subtle
         : theme.semantics.surface.default,
-      borderColor: fieldState.focused
-        ? theme.semantics.danger.base
-        : theme.semantics.danger.outline,
+      borderColor: fieldState.focused ? theme.semantics.error.base : theme.semantics.error.outline,
       contentColor: theme.semantics.content.default,
       placeholderColor: theme.semantics.content.muted,
     };

package/src/internal/resolvers/resolveSelectionControlColors.test.ts

@@ -5,12 +5,12 @@ import { resolveFieldState } from './resolveFieldState';
 import { resolveSelectionControlColors } from './resolveSelectionControlColors';
 
 describe('resolveSelectionControlColors', () => {
-  it('maps checked controls through the selected tone semantics', () => {
+  it('maps checked controls through the selected color semantics', () => {
     const theme = createTheme();
     const colors = resolveSelectionControlColors(theme, {
       checked: true,
       fieldState: resolveFieldState({ focused: true }),
-      tone: 'primary',
+      color: 'primary',
     });
 
     expect(colors.borderColor).toBe(theme.semantics.action.primary.base);
@@ -18,24 +18,24 @@ describe('resolveSelectionControlColors', () => {
     expect(colors.labelColor).toBe(theme.semantics.content.default);
   });
 
-  it('maps invalid unchecked controls through danger/border semantics', () => {
+  it('maps invalid unchecked controls through error/border semantics', () => {
     const theme = createTheme();
     const colors = resolveSelectionControlColors(theme, {
       checked: false,
       fieldState: resolveFieldState({ invalid: true }),
-      tone: 'primary',
+      color: 'primary',
     });
 
-    expect(colors.borderColor).toBe(theme.semantics.danger.outline);
-    expect(colors.trackColor).toBe(theme.semantics.danger.outline);
+    expect(colors.borderColor).toBe(theme.semantics.error.outline);
+    expect(colors.trackColor).toBe(theme.semantics.error.outline);
   });
 
-  it('mutes disabled controls regardless of tone', () => {
+  it('mutes disabled controls regardless of color', () => {
     const theme = createTheme();
     const colors = resolveSelectionControlColors(theme, {
       checked: true,
       fieldState: resolveFieldState({ disabled: true }),
-      tone: 'danger',
+      color: 'danger',
     });
 
     expect(colors.labelColor).toBe(theme.semantics.content.muted);

package/src/internal/resolvers/resolveSelectionControlColors.ts

@@ -1,6 +1,7 @@
+import type { SurfaceColor } from '../../surfaceColor';
 import type { SurfaceTheme } from '../../theme/types';
 import type { FieldState } from './resolveFieldState';
-import { type ComponentTone, resolveTone } from './resolveTone';
+import { resolveSurfaceColor } from './resolveSurfaceColor';
 
 export interface ResolvedSelectionControlColors {
   backgroundColor: string;
@@ -15,20 +16,20 @@ export interface ResolvedSelectionControlColors {
 export function resolveSelectionControlColors(
   theme: SurfaceTheme,
   {
-    tone = 'primary',
+    color = 'primary',
     fieldState,
     checked,
     hovered = false,
     pressed = false,
   }: {
-    tone?: ComponentTone;
+    color?: SurfaceColor;
     fieldState: FieldState;
     checked: boolean;
     hovered?: boolean;
     pressed?: boolean;
   },
 ): ResolvedSelectionControlColors {
-  const semanticTone = resolveTone(theme, fieldState.invalid ? 'danger' : tone);
+  const semanticTone = resolveSurfaceColor(theme, fieldState.invalid ? 'error' : color);
   const isMuted = fieldState.disabled;
   const isInteractiveReadOnly = fieldState.readOnly && !fieldState.disabled;
 
@@ -47,7 +48,7 @@ export function resolveSelectionControlColors(
   }
 
   const uncheckedBorderColor = fieldState.invalid
-    ? theme.semantics.danger.outline
+    ? theme.semantics.error.outline
     : fieldState.focused
       ? theme.semantics.border.focus
       : theme.semantics.border.strong;

package/src/internal/resolvers/resolveSurfaceColor.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveSurfaceColor } from './resolveSurfaceColor';
+
+describe('resolveSurfaceColor', () => {
+  it('maps every public surface color to a semantic role', () => {
+    const theme = createTheme();
+
+    expect(resolveSurfaceColor(theme, 'primary')).toBe(theme.semantics.action.primary);
+    expect(resolveSurfaceColor(theme, 'secondary')).toBe(theme.semantics.secondary);
+    expect(resolveSurfaceColor(theme, 'tertiary')).toBe(theme.semantics.accent);
+    expect(resolveSurfaceColor(theme, 'quaternary')).toBe(theme.semantics.highlight);
+    expect(resolveSurfaceColor(theme, 'neutral')).toBe(theme.semantics.action.neutral);
+    expect(resolveSurfaceColor(theme, 'success')).toBe(theme.semantics.success);
+    expect(resolveSurfaceColor(theme, 'warning')).toBe(theme.semantics.warning);
+    expect(resolveSurfaceColor(theme, 'error')).toBe(theme.semantics.error);
+    expect(resolveSurfaceColor(theme, 'info')).toBe(theme.semantics.info);
+    expect(resolveSurfaceColor(theme, 'danger')).toBe(theme.semantics.action.danger);
+  });
+});

package/src/internal/resolvers/resolveSurfaceColor.ts

@@ -0,0 +1,31 @@
+import type { SurfaceColor } from '../../surfaceColor';
+import type { RoleSemantics, SurfaceTheme } from '../../theme/types';
+
+export function resolveSurfaceColor(
+  theme: SurfaceTheme,
+  color: SurfaceColor = 'primary',
+): RoleSemantics {
+  switch (color) {
+    case 'secondary':
+      return theme.semantics.secondary;
+    case 'tertiary':
+      return theme.semantics.accent;
+    case 'quaternary':
+      return theme.semantics.highlight;
+    case 'neutral':
+      return theme.semantics.action.neutral;
+    case 'error':
+      return theme.semantics.error;
+    case 'info':
+      return theme.semantics.info;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'primary':
+    default:
+      return theme.semantics.action.primary;
+  }
+}

package/src/internal/resolvers/resolveTextColor.test.ts

@@ -4,7 +4,7 @@ import { createTheme } from '../../theme/createTheme';
 import { resolveTextColor } from './resolveTextColor';
 
 describe('resolveTextColor', () => {
-  it('maps semantic text tones through content aliases', () => {
+  it('maps semantic text emphases through content aliases', () => {
     const theme = createTheme();
 
     expect(resolveTextColor(theme, 'default')).toBe(theme.semantics.content.default);
@@ -13,11 +13,22 @@ describe('resolveTextColor', () => {
     expect(resolveTextColor(theme, 'inverse')).toBe(theme.semantics.content.inverse);
   });
 
-  it('supports semantic status tones for shared field and messaging copy', () => {
+  it('supports semantic colors for shared field and messaging copy', () => {
     const theme = createTheme();
 
-    expect(resolveTextColor(theme, 'danger')).toBe(theme.semantics.danger.base);
-    expect(resolveTextColor(theme, 'success')).toBe(theme.semantics.success.base);
-    expect(resolveTextColor(theme, 'warning')).toBe(theme.semantics.warning.base);
+    expect(resolveTextColor(theme, 'default', 'danger')).toBe(theme.semantics.action.danger.base);
+    expect(resolveTextColor(theme, 'default', 'success')).toBe(theme.semantics.success.base);
+    expect(resolveTextColor(theme, 'default', 'warning')).toBe(theme.semantics.warning.base);
+    expect(resolveTextColor(theme, 'default', 'error')).toBe(theme.semantics.error.base);
+    expect(resolveTextColor(theme, 'default', 'info')).toBe(theme.semantics.info.base);
+  });
+
+  it('maps inverse emphasis with a semantic color to role foreground text', () => {
+    const theme = createTheme();
+
+    expect(resolveTextColor(theme, 'inverse', 'primary')).toBe(
+      theme.semantics.action.primary.onSolidText,
+    );
+    expect(resolveTextColor(theme, 'inverse', 'error')).toBe(theme.semantics.error.onSolidText);
   });
 });

package/src/internal/resolvers/resolveTextColor.ts

@@ -1,39 +1,27 @@
-import { resolveToken } from '../../theme/resolveToken';
+import type { SurfaceColor, SurfaceEmphasis } from '../../surfaceColor';
 import type { SurfaceTheme } from '../../theme/types';
-
-export type TextTone =
-  | 'default'
-  | 'muted'
-  | 'subtle'
-  | 'inverse'
-  | 'danger'
-  | 'success'
-  | 'warning';
-export type TextColorValue = keyof SurfaceTheme['colors'] | string;
+import { resolveSurfaceColor } from './resolveSurfaceColor';
 
 export function resolveTextColor(
   theme: SurfaceTheme,
-  tone: TextTone = 'default',
-  color?: TextColorValue,
+  emphasis: SurfaceEmphasis = 'default',
+  color?: SurfaceColor,
 ): string {
   if (color) {
-    return resolveToken(theme.colors, color);
+    if (emphasis === 'inverse') {
+      return resolveSurfaceColor(theme, color).onSolidText;
+    }
+
+    return resolveSurfaceColor(theme, color).base;
   }
 
-  switch (tone) {
+  switch (emphasis) {
     case 'muted':
       return theme.semantics.content.muted;
     case 'subtle':
       return theme.semantics.content.subtle;
     case 'inverse':
       return theme.semantics.content.inverse;
-    case 'danger':
-      return theme.semantics.danger.base;
-    case 'success':
-      return theme.semantics.success.base;
-    case 'warning':
-      return theme.semantics.warning.base;
-    case 'default':
     default:
       return theme.semantics.content.default;
   }

package/src/layout/ScrollArea.tsx

@@ -0,0 +1,115 @@
+import React from 'react';
+import {
+  ScrollView,
+  type ScrollViewProps as ReactNativeScrollViewProps,
+  type StyleProp,
+  type ViewStyle,
+} from 'react-native';
+
+import { useResponsiveRuntime } from '../core/responsive';
+import { useTheme } from '../theme/ThemeContext';
+import { type BoxStyleProps, resolveBoxStyles } from './helpers';
+
+export interface ScrollAreaProps
+  extends
+    BoxStyleProps,
+    Omit<ReactNativeScrollViewProps, 'children' | 'contentContainerStyle' | 'style'> {
+  children?: React.ReactNode;
+  contentContainerStyle?: StyleProp<ViewStyle>;
+}
+
+export function ScrollArea({
+  children,
+  contentContainerStyle,
+  p,
+  px,
+  py,
+  pt,
+  pb,
+  pl,
+  pr,
+  m,
+  mx,
+  my,
+  mt,
+  mb,
+  ml,
+  mr,
+  bg,
+  radius,
+  borderWidth,
+  borderColor,
+  width,
+  height,
+  minWidth,
+  maxWidth,
+  minHeight,
+  maxHeight,
+  flex,
+  flexGrow,
+  flexShrink,
+  flexBasis,
+  alignSelf,
+  position,
+  top,
+  bottom,
+  left,
+  right,
+  overflow,
+  zIndex,
+  opacity,
+  style,
+  ...scrollProps
+}: ScrollAreaProps) {
+  const { theme } = useTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const resolved = resolveBoxStyles(theme, breakpoint, {
+    p,
+    px,
+    py,
+    pt,
+    pb,
+    pl,
+    pr,
+    m,
+    mx,
+    my,
+    mt,
+    mb,
+    ml,
+    mr,
+    bg,
+    radius,
+    borderWidth,
+    borderColor,
+    width,
+    height,
+    minWidth,
+    maxWidth,
+    minHeight,
+    maxHeight,
+    flex,
+    flexGrow,
+    flexShrink,
+    flexBasis,
+    alignSelf,
+    position,
+    top,
+    bottom,
+    left,
+    right,
+    overflow,
+    zIndex,
+    opacity,
+  });
+
+  return (
+    <ScrollView
+      {...scrollProps}
+      contentContainerStyle={contentContainerStyle}
+      style={[resolved, style]}
+    >
+      {children}
+    </ScrollView>
+  );
+}

package/src/layout/index.ts

@@ -12,6 +12,8 @@ export type { GridProps } from './Grid';
 export { Grid } from './Grid';
 export type { InlineProps } from './Inline';
 export { Inline } from './Inline';
+export type { ScrollAreaProps } from './ScrollArea';
+export { ScrollArea } from './ScrollArea';
 export type { ShowProps } from './Show';
 export { Show } from './Show';
 export type { SpacerProps } from './Spacer';

package/src/primitives/heading/Heading.tsx

@@ -39,6 +39,8 @@ export const Heading: React.FC<HeadingProps> = ({
   children,
   level = 2,
   align,
+  color,
+  emphasis = 'default',
   numberOfLines,
   i18nKey,
   testID,
@@ -52,7 +54,7 @@ export const Heading: React.FC<HeadingProps> = ({
       accessibilityRole="header"
       testID={testID}
       numberOfLines={numberOfLines}
-      style={resolveHeadingTextStyle(theme, level, align)}
+      style={resolveHeadingTextStyle(theme, level, align, emphasis, color)}
     >
       {content}
     </Text>

package/src/primitives/heading/resolveHeadingStyle.test.ts

@@ -22,7 +22,7 @@ describe('resolveHeadingTextStyle', () => {
     expect(style.fontFamily).toBe('SpaceGrotesk_700Regular');
   });
 
-  it('shares the default content tone with the text primitive', () => {
+  it('shares the default content emphasis with the text primitive', () => {
     const theme = createTheme();
     const style = resolveHeadingTextStyle(theme, 2);