@ankhorage/surface 0.1.4 → 0.1.6

package/src/internal/resolvers/resolveInteractiveColors.ts

@@ -0,0 +1,134 @@
+import type { AnkhTheme } from '../../theme/types';
+import type { FieldState } from './resolveFieldState';
+import type { InteractionState } from './resolveInteractiveState';
+import { type ComponentTone, resolveTone } from './resolveTone';
+
+export type ButtonVariant = 'solid' | 'outline' | 'ghost' | 'soft';
+
+export interface ResolvedInteractiveColors {
+  backgroundColor: string;
+  borderColor: string;
+  contentColor: string;
+  opacity?: number;
+}
+
+export function resolveButtonColors(
+  theme: AnkhTheme,
+  {
+    variant,
+    tone,
+    state,
+  }: {
+    variant: ButtonVariant;
+    tone: ComponentTone;
+    state: InteractionState;
+  },
+): ResolvedInteractiveColors {
+  if (state.disabled) {
+    return {
+      backgroundColor: theme.semantics.neutral.surface,
+      borderColor: theme.semantics.neutral.divider,
+      contentColor: theme.semantics.content.muted,
+      opacity: 0.72,
+    };
+  }
+
+  const semanticTone = resolveTone(theme, tone);
+
+  switch (variant) {
+    case 'outline':
+      return {
+        backgroundColor: state.pressed
+          ? semanticTone.softActive
+          : state.hovered
+            ? semanticTone.softHover
+            : 'transparent',
+        borderColor: semanticTone.outline,
+        contentColor: semanticTone.base,
+      };
+    case 'ghost':
+      return {
+        backgroundColor: state.pressed
+          ? semanticTone.softActive
+          : state.hovered
+            ? semanticTone.softHover
+            : 'transparent',
+        borderColor: 'transparent',
+        contentColor: semanticTone.base,
+      };
+    case 'soft':
+      return {
+        backgroundColor: state.pressed
+          ? semanticTone.softActive
+          : state.hovered
+            ? semanticTone.softHover
+            : semanticTone.softBg,
+        borderColor: 'transparent',
+        contentColor: semanticTone.base,
+      };
+    case 'solid':
+    default:
+      return {
+        backgroundColor: state.pressed
+          ? semanticTone.strong
+          : state.hovered
+            ? semanticTone.hover
+            : semanticTone.base,
+        borderColor: semanticTone.base,
+        contentColor: semanticTone.onSolidText,
+      };
+  }
+}
+
+export function resolveInputColors(
+  theme: AnkhTheme,
+  fieldState: FieldState,
+): ResolvedInteractiveColors & { placeholderColor: string } {
+  if (fieldState.disabled) {
+    return {
+      backgroundColor: theme.semantics.surface.subtle,
+      borderColor: theme.semantics.border.default,
+      contentColor: theme.semantics.content.muted,
+      placeholderColor: theme.semantics.content.subtle,
+      opacity: 0.72,
+    };
+  }
+
+  if (fieldState.invalid) {
+    return {
+      backgroundColor: fieldState.readOnly
+        ? theme.semantics.surface.subtle
+        : theme.semantics.surface.default,
+      borderColor: fieldState.focused
+        ? theme.semantics.danger.base
+        : theme.semantics.danger.outline,
+      contentColor: theme.semantics.content.default,
+      placeholderColor: theme.semantics.content.muted,
+    };
+  }
+
+  if (fieldState.focused) {
+    return {
+      backgroundColor: theme.semantics.surface.default,
+      borderColor: theme.semantics.border.focus,
+      contentColor: theme.semantics.content.default,
+      placeholderColor: theme.semantics.content.muted,
+    };
+  }
+
+  if (fieldState.readOnly) {
+    return {
+      backgroundColor: theme.semantics.surface.subtle,
+      borderColor: theme.semantics.border.default,
+      contentColor: theme.semantics.content.default,
+      placeholderColor: theme.semantics.content.muted,
+    };
+  }
+
+  return {
+    backgroundColor: theme.semantics.surface.default,
+    borderColor: theme.semantics.border.default,
+    contentColor: theme.semantics.content.default,
+    placeholderColor: theme.semantics.content.muted,
+  };
+}

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

@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveInteractiveState } from './resolveInteractiveState';
+
+describe('resolveInteractiveState', () => {
+  it('freezes the interaction state shape to booleans', () => {
+    expect(resolveInteractiveState({ hovered: true, pressed: 1 as never })).toEqual({
+      pressed: true,
+      hovered: true,
+      focused: false,
+      disabled: false,
+    });
+  });
+});

package/src/internal/resolvers/resolveInteractiveState.ts

@@ -0,0 +1,15 @@
+export interface InteractionState {
+  pressed: boolean;
+  hovered: boolean;
+  focused: boolean;
+  disabled: boolean;
+}
+
+export function resolveInteractiveState(input: Partial<InteractionState>): InteractionState {
+  return {
+    pressed: Boolean(input.pressed),
+    hovered: Boolean(input.hovered),
+    focused: Boolean(input.focused),
+    disabled: Boolean(input.disabled),
+  };
+}

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveOverlayAnimation } from './resolveOverlayAnimation';
+
+describe('resolveOverlayAnimation', () => {
+  it('returns stable transition values for each overlay layer', () => {
+    const modal = resolveOverlayAnimation('modal');
+    const drawer = resolveOverlayAnimation('drawer');
+    const tooltip = resolveOverlayAnimation('tooltip');
+
+    expect(modal.backdropOpacity).toBeGreaterThan(drawer.backdropOpacity);
+    expect(drawer.offset).toBeGreaterThan(tooltip.offset);
+    expect(tooltip.enterDuration).toBeLessThan(modal.enterDuration);
+  });
+});

package/src/internal/resolvers/resolveOverlayAnimation.ts

@@ -0,0 +1,24 @@
+import type { OverlayLayer } from './resolveOverlayZIndex';
+
+export interface OverlayAnimationValues {
+  enterDuration: number;
+  exitDuration: number;
+  backdropOpacity: number;
+  offset: number;
+}
+
+export function resolveOverlayAnimation(layer: OverlayLayer): OverlayAnimationValues {
+  switch (layer) {
+    case 'drawer':
+      return { enterDuration: 180, exitDuration: 140, backdropOpacity: 0.26, offset: 24 };
+    case 'tooltip':
+      return { enterDuration: 90, exitDuration: 90, backdropOpacity: 0, offset: 8 };
+    case 'toast':
+      return { enterDuration: 140, exitDuration: 120, backdropOpacity: 0, offset: 12 };
+    case 'menu':
+      return { enterDuration: 110, exitDuration: 110, backdropOpacity: 0.04, offset: 6 };
+    case 'modal':
+    default:
+      return { enterDuration: 160, exitDuration: 140, backdropOpacity: 0.32, offset: 12 };
+  }
+}

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

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveOverlayZIndex } from './resolveOverlayZIndex';
+
+describe('resolveOverlayZIndex', () => {
+  it('assigns higher base layers to later overlay types', () => {
+    expect(resolveOverlayZIndex('modal')).toBeLessThan(resolveOverlayZIndex('menu'));
+    expect(resolveOverlayZIndex('menu')).toBeLessThan(resolveOverlayZIndex('tooltip'));
+    expect(resolveOverlayZIndex('tooltip')).toBeLessThan(resolveOverlayZIndex('toast'));
+  });
+
+  it('increments the z-index within the same layer stack', () => {
+    expect(resolveOverlayZIndex('modal', 1)).toBe(resolveOverlayZIndex('modal', 0) + 1);
+  });
+});

package/src/internal/resolvers/resolveOverlayZIndex.ts

@@ -0,0 +1,13 @@
+export type OverlayLayer = 'modal' | 'drawer' | 'menu' | 'tooltip' | 'toast';
+
+const BASE_Z_INDEX: Record<OverlayLayer, number> = {
+  modal: 1000,
+  drawer: 1100,
+  menu: 1200,
+  tooltip: 1300,
+  toast: 1400,
+};
+
+export function resolveOverlayZIndex(layer: OverlayLayer, stackIndex = 0): number {
+  return BASE_Z_INDEX[layer] + stackIndex;
+}

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveSelectionControlNextChecked } from './resolveSelectionControlBehavior';
+
+describe('resolveSelectionControlNextChecked', () => {
+  it('toggles checkbox and switch values when interactive', () => {
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: false,
+        kind: 'checkbox',
+      }),
+    ).toBe(true);
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: true,
+        kind: 'switch',
+      }),
+    ).toBe(false);
+  });
+
+  it('allows radio selection once but not repeat activation', () => {
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: false,
+        kind: 'radio',
+      }),
+    ).toBe(true);
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: true,
+        kind: 'radio',
+      }),
+    ).toBeNull();
+  });
+
+  it('keeps read-only and disabled controls focusable but non-mutating', () => {
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: false,
+        kind: 'checkbox',
+        readOnly: true,
+      }),
+    ).toBeNull();
+    expect(
+      resolveSelectionControlNextChecked({
+        checked: false,
+        disabled: true,
+        kind: 'switch',
+      }),
+    ).toBeNull();
+  });
+});

package/src/internal/resolvers/resolveSelectionControlBehavior.ts

@@ -0,0 +1,23 @@
+export type SelectionControlKind = 'checkbox' | 'radio' | 'switch';
+
+export function resolveSelectionControlNextChecked({
+  kind,
+  checked,
+  disabled = false,
+  readOnly = false,
+}: {
+  kind: SelectionControlKind;
+  checked: boolean;
+  disabled?: boolean;
+  readOnly?: boolean;
+}): boolean | null {
+  if (disabled || readOnly) {
+    return null;
+  }
+
+  if (kind === 'radio') {
+    return checked ? null : true;
+  }
+
+  return !checked;
+}

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveFieldState } from './resolveFieldState';
+import { resolveSelectionControlColors } from './resolveSelectionControlColors';
+
+describe('resolveSelectionControlColors', () => {
+  it('maps checked controls through the selected tone semantics', () => {
+    const theme = createTheme();
+    const colors = resolveSelectionControlColors(theme, {
+      checked: true,
+      fieldState: resolveFieldState({ focused: true }),
+      tone: 'primary',
+    });
+
+    expect(colors.borderColor).toBe(theme.semantics.action.primary.base);
+    expect(colors.indicatorColor).toBe(theme.semantics.action.primary.onSolidText);
+    expect(colors.labelColor).toBe(theme.semantics.content.default);
+  });
+
+  it('maps invalid unchecked controls through danger/border semantics', () => {
+    const theme = createTheme();
+    const colors = resolveSelectionControlColors(theme, {
+      checked: false,
+      fieldState: resolveFieldState({ invalid: true }),
+      tone: 'primary',
+    });
+
+    expect(colors.borderColor).toBe(theme.semantics.danger.outline);
+    expect(colors.trackColor).toBe(theme.semantics.danger.outline);
+  });
+
+  it('mutes disabled controls regardless of tone', () => {
+    const theme = createTheme();
+    const colors = resolveSelectionControlColors(theme, {
+      checked: true,
+      fieldState: resolveFieldState({ disabled: true }),
+      tone: 'danger',
+    });
+
+    expect(colors.labelColor).toBe(theme.semantics.content.muted);
+    expect(colors.opacity).toBe(0.72);
+  });
+});

package/src/internal/resolvers/resolveSelectionControlColors.ts

@@ -0,0 +1,81 @@
+import type { AnkhTheme } from '../../theme/types';
+import type { FieldState } from './resolveFieldState';
+import { type ComponentTone, resolveTone } from './resolveTone';
+
+export interface ResolvedSelectionControlColors {
+  backgroundColor: string;
+  borderColor: string;
+  indicatorColor: string;
+  labelColor: string;
+  trackColor: string;
+  thumbColor: string;
+  opacity?: number;
+}
+
+export function resolveSelectionControlColors(
+  theme: AnkhTheme,
+  {
+    tone = 'primary',
+    fieldState,
+    checked,
+    hovered = false,
+    pressed = false,
+  }: {
+    tone?: ComponentTone;
+    fieldState: FieldState;
+    checked: boolean;
+    hovered?: boolean;
+    pressed?: boolean;
+  },
+): ResolvedSelectionControlColors {
+  const semanticTone = resolveTone(theme, fieldState.invalid ? 'danger' : tone);
+  const isMuted = fieldState.disabled;
+  const isInteractiveReadOnly = fieldState.readOnly && !fieldState.disabled;
+
+  if (isMuted) {
+    return {
+      backgroundColor: checked
+        ? theme.semantics.neutral.surfaceActive
+        : theme.semantics.surface.subtle,
+      borderColor: theme.semantics.border.default,
+      indicatorColor: checked ? theme.semantics.content.muted : 'transparent',
+      labelColor: theme.semantics.content.muted,
+      trackColor: checked ? theme.semantics.neutral.surfaceActive : theme.semantics.neutral.border,
+      thumbColor: theme.semantics.surface.default,
+      opacity: 0.72,
+    };
+  }
+
+  const uncheckedBorderColor = fieldState.invalid
+    ? theme.semantics.danger.outline
+    : fieldState.focused
+      ? theme.semantics.border.focus
+      : theme.semantics.border.strong;
+  const uncheckedBackgroundColor = pressed
+    ? theme.semantics.neutral.surfaceActive
+    : hovered
+      ? theme.semantics.neutral.surfaceHover
+      : theme.semantics.surface.default;
+  const checkedBackgroundColor = pressed
+    ? semanticTone.strong
+    : hovered
+      ? semanticTone.hover
+      : semanticTone.base;
+  const checkedTrackColor = pressed
+    ? semanticTone.strong
+    : hovered
+      ? semanticTone.hover
+      : semanticTone.base;
+
+  return {
+    backgroundColor: checked ? checkedBackgroundColor : uncheckedBackgroundColor,
+    borderColor: checked ? semanticTone.base : uncheckedBorderColor,
+    indicatorColor: checked ? semanticTone.onSolidText : 'transparent',
+    labelColor: isInteractiveReadOnly
+      ? theme.semantics.content.muted
+      : theme.semantics.content.default,
+    trackColor: checked ? checkedTrackColor : uncheckedBorderColor,
+    thumbColor: checked ? semanticTone.onSolidText : theme.semantics.surface.default,
+    opacity: isInteractiveReadOnly ? 0.88 : 1,
+  };
+}

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

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveTextColor } from './resolveTextColor';
+
+describe('resolveTextColor', () => {
+  it('maps semantic text tones through content aliases', () => {
+    const theme = createTheme();
+
+    expect(resolveTextColor(theme, 'default')).toBe(theme.semantics.content.default);
+    expect(resolveTextColor(theme, 'muted')).toBe(theme.semantics.content.muted);
+    expect(resolveTextColor(theme, 'subtle')).toBe(theme.semantics.content.subtle);
+    expect(resolveTextColor(theme, 'inverse')).toBe(theme.semantics.content.inverse);
+  });
+
+  it('supports semantic status tones 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);
+  });
+});

package/src/internal/resolvers/resolveTextColor.ts

@@ -0,0 +1,40 @@
+import { resolveToken } from '../../theme/resolveToken';
+import type { AnkhTheme } from '../../theme/types';
+
+export type TextTone =
+  | 'default'
+  | 'muted'
+  | 'subtle'
+  | 'inverse'
+  | 'danger'
+  | 'success'
+  | 'warning';
+export type TextColorValue = keyof AnkhTheme['colors'] | string;
+
+export function resolveTextColor(
+  theme: AnkhTheme,
+  tone: TextTone = 'default',
+  color?: TextColorValue,
+): string {
+  if (color) {
+    return resolveToken(theme.colors, color);
+  }
+
+  switch (tone) {
+    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/internal/resolvers/resolveTextStyles.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveTextStyles } from './resolveTextStyles';
+
+describe('resolveTextStyles', () => {
+  it('maps body and label variants to theme-driven typography', () => {
+    const theme = createTheme();
+
+    const body = resolveTextStyles(theme, { variant: 'body' });
+    const label = resolveTextStyles(theme, { variant: 'label' });
+
+    expect(body.fontSize).toBe(theme.typography.sizes.m);
+    expect(body.lineHeight).toBe(24);
+    expect(label.fontSize).toBe(theme.typography.sizes.s);
+    expect(label.fontWeight).toBe(theme.typography.weights.medium);
+  });
+
+  it('resolves heading levels through the shared text resolver', () => {
+    const theme = createTheme(undefined, 'light', 'space grotesk');
+    const style = resolveTextStyles(theme, { level: 1 });
+
+    expect(style.fontSize).toBe(theme.typography.headings[1].size);
+    expect(style.fontWeight).toBe(theme.typography.weights.bold);
+    expect(style.fontFamily).toBe('SpaceGrotesk_700Regular');
+  });
+});

package/src/internal/resolvers/resolveTextStyles.ts

@@ -0,0 +1,95 @@
+import type { TextStyle } from 'react-native';
+
+import type { AnkhTheme, FontWeight } from '../../theme/types';
+
+export type TextVariant = 'body' | 'bodySmall' | 'caption' | 'label' | 'mono';
+export type TextWeight = keyof AnkhTheme['typography']['weights'] | FontWeight;
+
+interface VariantStyle {
+  fontSize: number;
+  lineHeight: number;
+  weight: TextWeight;
+}
+
+export interface ResolveTextStyleOptions {
+  variant?: TextVariant;
+  align?: TextStyle['textAlign'];
+  weight?: TextWeight;
+  italic?: boolean;
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+}
+
+function resolveWeight(theme: AnkhTheme, value: TextWeight | undefined): FontWeight {
+  if (!value) return theme.typography.weights.regular;
+  if (value in theme.typography.weights) {
+    return theme.typography.weights[value as keyof AnkhTheme['typography']['weights']];
+  }
+  return value as FontWeight;
+}
+
+function getVariantStyle(theme: AnkhTheme, variant: TextVariant): VariantStyle {
+  switch (variant) {
+    case 'bodySmall':
+      return {
+        fontSize: theme.typography.sizes.s,
+        lineHeight: 20,
+        weight: 'regular',
+      };
+    case 'caption':
+      return {
+        fontSize: theme.typography.sizes.xs,
+        lineHeight: 16,
+        weight: 'regular',
+      };
+    case 'label':
+      return {
+        fontSize: theme.typography.sizes.s,
+        lineHeight: 18,
+        weight: 'medium',
+      };
+    case 'mono':
+      return {
+        fontSize: theme.typography.sizes.s,
+        lineHeight: 20,
+        weight: 'regular',
+      };
+    case 'body':
+    default:
+      return {
+        fontSize: theme.typography.sizes.m,
+        lineHeight: 24,
+        weight: 'regular',
+      };
+  }
+}
+
+export function resolveTextStyles(
+  theme: AnkhTheme,
+  options: ResolveTextStyleOptions = {},
+): TextStyle {
+  const { level, variant = 'body', align, weight, italic = false } = options;
+  const headingTypography = level ? theme.typography.headings[level] : null;
+  const variantStyle = headingTypography
+    ? {
+        fontSize: headingTypography.size,
+        lineHeight: headingTypography.lineHeight,
+        weight: headingTypography.weight,
+      }
+    : getVariantStyle(theme, variant);
+
+  const resolvedWeight = resolveWeight(theme, weight ?? variantStyle.weight);
+  const isMono = !level && variant === 'mono';
+  const fontFamily = isMono
+    ? 'monospace'
+    : theme.typography.fonts[italic ? 'italic' : 'normal'][resolvedWeight];
+
+  return {
+    fontSize: variantStyle.fontSize,
+    lineHeight: variantStyle.lineHeight,
+    fontWeight: resolvedWeight,
+    fontFamily,
+    fontStyle: italic ? 'italic' : 'normal',
+    textAlign: align,
+    elevation: 0,
+  };
+}

package/src/internal/resolvers/resolveTone.ts

@@ -0,0 +1,19 @@
+import type { AnkhTheme, RoleSemantics } from '../../theme/types';
+
+export type ComponentTone = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+
+export function resolveTone(theme: AnkhTheme, tone: ComponentTone = 'primary'): RoleSemantics {
+  switch (tone) {
+    case 'neutral':
+      return theme.semantics.action.neutral;
+    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/useControllableState.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+
+export function useControllableState<T>({
+  value,
+  defaultValue,
+  onChange,
+}: {
+  value: T | undefined;
+  defaultValue: T;
+  onChange?: ((nextValue: T) => void) | undefined;
+}) {
+  const [uncontrolledValue, setUncontrolledValue] = React.useState(defaultValue);
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value : uncontrolledValue;
+
+  const setValue = React.useCallback(
+    (nextValue: T) => {
+      if (!isControlled) {
+        setUncontrolledValue(nextValue);
+      }
+
+      onChange?.(nextValue);
+    },
+    [isControlled, onChange],
+  );
+
+  return [currentValue, setValue] as const;
+}