@ankhorage/surface 0.1.4 → 0.1.6

package/src/internal/overlay/OverlayProvider.tsx

@@ -0,0 +1,74 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import {
+  createOverlayEntry,
+  type OverlayDescriptor,
+  type OverlayEntry,
+  OverlayStackContext,
+  sortOverlayEntries,
+} from './useOverlayStack';
+
+export function OverlayProvider({ children }: { children: React.ReactNode }) {
+  const orderRef = React.useRef(0);
+  const [overlays, setOverlays] = React.useState<OverlayEntry[]>([]);
+
+  const setOverlay = React.useCallback((id: string, descriptor: OverlayDescriptor) => {
+    setOverlays((current) => {
+      const existing = current.find((entry) => entry.id === id);
+      const nextEntry = createOverlayEntry(id, existing?.order ?? orderRef.current++, descriptor);
+
+      if (!existing) {
+        return sortOverlayEntries([...current, nextEntry]);
+      }
+
+      return sortOverlayEntries(current.map((entry) => (entry.id === id ? nextEntry : entry)));
+    });
+  }, []);
+
+  const removeOverlay = React.useCallback((id: string) => {
+    setOverlays((current) => current.filter((entry) => entry.id !== id));
+  }, []);
+
+  const value = React.useMemo(
+    () => ({
+      overlays,
+      removeOverlay,
+      setOverlay,
+    }),
+    [overlays, removeOverlay, setOverlay],
+  );
+
+  return (
+    <OverlayStackContext.Provider value={value}>
+      {children}
+      <View
+        pointerEvents="box-none"
+        style={{
+          bottom: 0,
+          left: 0,
+          position: 'absolute',
+          right: 0,
+          top: 0,
+        }}
+      >
+        {overlays.map((overlay) => (
+          <View
+            key={overlay.id}
+            pointerEvents="box-none"
+            style={{
+              bottom: 0,
+              left: 0,
+              position: 'absolute',
+              right: 0,
+              top: 0,
+              zIndex: overlay.zIndex,
+            }}
+          >
+            {overlay.node}
+          </View>
+        ))}
+      </View>
+    </OverlayStackContext.Provider>
+  );
+}

package/src/internal/overlay/Portal.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+
+import type { OverlayLayer } from '../resolvers/resolveOverlayZIndex';
+import { useOverlayStack } from './useOverlayStack';
+
+let portalCounter = 0;
+
+export interface PortalProps {
+  children?: React.ReactNode;
+  layer?: OverlayLayer;
+  visible?: boolean;
+}
+
+export function Portal({ children, layer = 'modal', visible = true }: PortalProps) {
+  const overlayStack = useOverlayStack();
+  const idRef = React.useRef(`surface-portal-${portalCounter++}`);
+
+  React.useEffect(() => {
+    if (!overlayStack || !visible || children === undefined || children === null) {
+      return undefined;
+    }
+
+    overlayStack.setOverlay(idRef.current, {
+      layer,
+      node: children,
+    });
+
+    return () => {
+      overlayStack.removeOverlay(idRef.current);
+    };
+  }, [children, layer, overlayStack, visible]);
+
+  if (!overlayStack) {
+    return visible ? <>{children}</> : null;
+  }
+
+  return null;
+}

package/src/internal/overlay/useOverlayStack.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+
+import { type OverlayEntry, sortOverlayEntries } from './useOverlayStack';
+
+describe('sortOverlayEntries', () => {
+  it('sorts overlays by z-index then registration order', () => {
+    const overlays: OverlayEntry[] = [
+      { id: 'menu-1', layer: 'menu', node: null, order: 2, zIndex: 1200 },
+      { id: 'modal-1', layer: 'modal', node: null, order: 0, zIndex: 1000 },
+      { id: 'menu-0', layer: 'menu', node: null, order: 1, zIndex: 1200 },
+    ];
+
+    expect(sortOverlayEntries(overlays).map((entry) => entry.id)).toEqual([
+      'modal-1',
+      'menu-0',
+      'menu-1',
+    ]);
+  });
+
+  it('recomputes per-layer stack indices to avoid z-index collisions after removals', () => {
+    const overlays: OverlayEntry[] = [
+      { id: 'menu-0', layer: 'menu', node: null, order: 1, zIndex: 1200 },
+      { id: 'menu-2', layer: 'menu', node: null, order: 3, zIndex: 1200 },
+    ];
+
+    const sorted = sortOverlayEntries(overlays);
+
+    expect(sorted[0]?.zIndex).toBe(1200);
+    expect(sorted[1]?.zIndex).toBe(1201);
+  });
+});

package/src/internal/overlay/useOverlayStack.ts

@@ -0,0 +1,61 @@
+import React from 'react';
+
+import { type OverlayLayer, resolveOverlayZIndex } from '../resolvers/resolveOverlayZIndex';
+
+export interface OverlayEntry {
+  id: string;
+  layer: OverlayLayer;
+  node: React.ReactNode;
+  order: number;
+  zIndex: number;
+}
+
+export interface OverlayDescriptor {
+  layer: OverlayLayer;
+  node: React.ReactNode;
+}
+
+export interface OverlayStackRuntime {
+  overlays: OverlayEntry[];
+  setOverlay: (id: string, overlay: OverlayDescriptor) => void;
+  removeOverlay: (id: string) => void;
+}
+
+export function sortOverlayEntries(entries: OverlayEntry[]): OverlayEntry[] {
+  const perLayerCounts: Partial<Record<OverlayLayer, number>> = {};
+  const normalizedEntries = [...entries]
+    .sort((left, right) => left.order - right.order)
+    .map((entry) => {
+      const stackIndex = perLayerCounts[entry.layer] ?? 0;
+      perLayerCounts[entry.layer] = stackIndex + 1;
+
+      return {
+        ...entry,
+        zIndex: resolveOverlayZIndex(entry.layer, stackIndex),
+      };
+    });
+
+  return normalizedEntries.sort((left, right) =>
+    left.zIndex === right.zIndex ? left.order - right.order : left.zIndex - right.zIndex,
+  );
+}
+
+export const OverlayStackContext = React.createContext<OverlayStackRuntime | null>(null);
+
+export function useOverlayStack(): OverlayStackRuntime | null {
+  return React.useContext(OverlayStackContext);
+}
+
+export function createOverlayEntry(
+  id: string,
+  order: number,
+  descriptor: OverlayDescriptor,
+): OverlayEntry {
+  return {
+    id,
+    layer: descriptor.layer,
+    node: descriptor.node,
+    order,
+    zIndex: resolveOverlayZIndex(descriptor.layer, 0),
+  };
+}

package/src/internal/resolvers/index.ts

@@ -0,0 +1,15 @@
+export * from './resolveControlSize';
+export * from './resolveFieldPresentation';
+export * from './resolveFieldState';
+export * from './resolveFocusRingStyles';
+export * from './resolveIconSize';
+export * from './resolveIndicatorSize';
+export * from './resolveInteractiveColors';
+export * from './resolveInteractiveState';
+export * from './resolveOverlayAnimation';
+export * from './resolveOverlayZIndex';
+export * from './resolveSelectionControlBehavior';
+export * from './resolveSelectionControlColors';
+export * from './resolveTextColor';
+export * from './resolveTextStyles';
+export * from './resolveTone';

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

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveControlSize } from './resolveControlSize';
+
+describe('resolveControlSize', () => {
+  it('returns a fixed control shape for each size', () => {
+    const theme = createTheme();
+    const small = resolveControlSize(theme, 's');
+    const medium = resolveControlSize(theme, 'm');
+    const large = resolveControlSize(theme, 'l');
+
+    expect(small).toEqual({
+      minHeight: 32,
+      paddingHorizontal: theme.spacing.s,
+      paddingVertical: 6,
+      borderRadius: theme.radii.m,
+      textVariant: 'bodySmall',
+      iconSize: 16,
+    });
+    expect(medium.minHeight).toBe(40);
+    expect(large.minHeight).toBe(48);
+    expect(large.iconSize).toBe(20);
+  });
+});

package/src/internal/resolvers/resolveControlSize.ts

@@ -0,0 +1,45 @@
+import type { AnkhTheme } from '../../theme/types';
+
+export type ControlSize = 's' | 'm' | 'l';
+
+export interface ResolvedControlSize {
+  minHeight: number;
+  paddingHorizontal: number;
+  paddingVertical: number;
+  borderRadius: number;
+  textVariant: 'bodySmall' | 'body';
+  iconSize: number;
+}
+
+export function resolveControlSize(theme: AnkhTheme, size: ControlSize = 'm'): ResolvedControlSize {
+  switch (size) {
+    case 's':
+      return {
+        minHeight: 32,
+        paddingHorizontal: theme.spacing.s,
+        paddingVertical: 6,
+        borderRadius: theme.radii.m,
+        textVariant: 'bodySmall',
+        iconSize: 16,
+      };
+    case 'l':
+      return {
+        minHeight: 48,
+        paddingHorizontal: 20,
+        paddingVertical: 10,
+        borderRadius: theme.radii.l,
+        textVariant: 'body',
+        iconSize: 20,
+      };
+    case 'm':
+    default:
+      return {
+        minHeight: 40,
+        paddingHorizontal: theme.spacing.m,
+        paddingVertical: 8,
+        borderRadius: theme.radii.m,
+        textVariant: 'body',
+        iconSize: 18,
+      };
+  }
+}

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

@@ -0,0 +1,31 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveFieldPresentation } from './resolveFieldPresentation';
+import { resolveFieldState } from './resolveFieldState';
+
+describe('resolveFieldPresentation', () => {
+  it('keeps label and helper tones aligned for default fields', () => {
+    expect(resolveFieldPresentation(resolveFieldState({}))).toEqual({
+      helperTone: 'default',
+      labelTone: 'default',
+    });
+  });
+
+  it('mutes both label and helper text for disabled and read-only fields', () => {
+    expect(resolveFieldPresentation(resolveFieldState({ disabled: true }))).toEqual({
+      helperTone: 'muted',
+      labelTone: 'muted',
+    });
+    expect(resolveFieldPresentation(resolveFieldState({ readOnly: true }))).toEqual({
+      helperTone: 'muted',
+      labelTone: 'muted',
+    });
+  });
+
+  it('elevates invalid fields to the danger tone', () => {
+    expect(resolveFieldPresentation(resolveFieldState({ invalid: true, readOnly: true }))).toEqual({
+      helperTone: 'danger',
+      labelTone: 'danger',
+    });
+  });
+});

package/src/internal/resolvers/resolveFieldPresentation.ts

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

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

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveFieldState } from './resolveFieldState';
+
+describe('resolveFieldState', () => {
+  it('applies field-state precedence consistently', () => {
+    expect(resolveFieldState({})).toEqual({
+      name: 'default',
+      focused: false,
+      disabled: false,
+      invalid: false,
+      readOnly: false,
+    });
+
+    expect(resolveFieldState({ focused: true }).name).toBe('focused');
+    expect(resolveFieldState({ readOnly: true }).name).toBe('readOnly');
+    expect(resolveFieldState({ invalid: true, focused: true }).name).toBe('invalid');
+    expect(resolveFieldState({ disabled: true, invalid: true, focused: true }).name).toBe(
+      'disabled',
+    );
+  });
+});

package/src/internal/resolvers/resolveFieldState.ts

@@ -0,0 +1,36 @@
+export type FieldStateName = 'default' | 'focused' | 'disabled' | 'invalid' | 'readOnly';
+
+export interface FieldState {
+  name: FieldStateName;
+  focused: boolean;
+  disabled: boolean;
+  invalid: boolean;
+  readOnly: boolean;
+}
+
+export function resolveFieldState({
+  focused = false,
+  disabled = false,
+  invalid = false,
+  readOnly = false,
+}: Partial<Omit<FieldState, 'name'>>): FieldState {
+  let name: FieldStateName = 'default';
+
+  if (disabled) {
+    name = 'disabled';
+  } else if (invalid) {
+    name = 'invalid';
+  } else if (focused) {
+    name = 'focused';
+  } else if (readOnly) {
+    name = 'readOnly';
+  }
+
+  return {
+    name,
+    focused,
+    disabled,
+    invalid,
+    readOnly,
+  };
+}

package/src/internal/resolvers/resolveFocusRingStyles.ts

@@ -0,0 +1,14 @@
+import type { ViewStyle } from 'react-native';
+
+export function resolveFocusRingStyles(color: string, focused: boolean, isWeb: boolean): ViewStyle {
+  if (!focused || !isWeb) {
+    return {};
+  }
+
+  return {
+    shadowColor: color,
+    shadowOpacity: 0.22,
+    shadowRadius: 6,
+    shadowOffset: { width: 0, height: 0 },
+  };
+}

package/src/internal/resolvers/resolveIconSize.ts

@@ -0,0 +1,6 @@
+import type { AnkhTheme } from '../../theme/types';
+import { type ControlSize, resolveControlSize } from './resolveControlSize';
+
+export function resolveIconSize(theme: AnkhTheme, size: ControlSize = 'm'): number {
+  return resolveControlSize(theme, size).iconSize;
+}

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

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveIndicatorSize } from './resolveIndicatorSize';
+
+describe('resolveIndicatorSize', () => {
+  it('returns a stable size map for each control size', () => {
+    expect(resolveIndicatorSize('s')).toEqual({
+      checkbox: 16,
+      checkboxIndicator: 10,
+      radio: 16,
+      radioDot: 8,
+      switchWidth: 30,
+      switchHeight: 18,
+      switchThumb: 12,
+    });
+    expect(resolveIndicatorSize('m').switchWidth).toBe(34);
+    expect(resolveIndicatorSize('l').switchThumb).toBe(18);
+  });
+});

package/src/internal/resolvers/resolveIndicatorSize.ts

@@ -0,0 +1,47 @@
+import type { ControlSize } from './resolveControlSize';
+
+export interface ResolvedIndicatorSize {
+  checkbox: number;
+  checkboxIndicator: number;
+  radio: number;
+  radioDot: number;
+  switchWidth: number;
+  switchHeight: number;
+  switchThumb: number;
+}
+
+export function resolveIndicatorSize(size: ControlSize = 'm'): ResolvedIndicatorSize {
+  switch (size) {
+    case 's':
+      return {
+        checkbox: 16,
+        checkboxIndicator: 10,
+        radio: 16,
+        radioDot: 8,
+        switchWidth: 30,
+        switchHeight: 18,
+        switchThumb: 12,
+      };
+    case 'l':
+      return {
+        checkbox: 22,
+        checkboxIndicator: 14,
+        radio: 22,
+        radioDot: 10,
+        switchWidth: 42,
+        switchHeight: 26,
+        switchThumb: 18,
+      };
+    case 'm':
+    default:
+      return {
+        checkbox: 18,
+        checkboxIndicator: 12,
+        radio: 18,
+        radioDot: 8,
+        switchWidth: 34,
+        switchHeight: 22,
+        switchThumb: 14,
+      };
+  }
+}

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

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'bun:test';
+
+import { createTheme } from '../../theme/createTheme';
+import { resolveFieldState } from './resolveFieldState';
+import { resolveButtonColors, resolveInputColors } from './resolveInteractiveColors';
+
+describe('resolveInteractiveColors', () => {
+  it('maps button variant, tone, and state through semantic slots', () => {
+    const theme = createTheme();
+    const solid = resolveButtonColors(theme, {
+      variant: 'solid',
+      tone: 'primary',
+      state: {
+        disabled: false,
+        focused: false,
+        hovered: false,
+        pressed: false,
+      },
+    });
+    const outline = resolveButtonColors(theme, {
+      variant: 'outline',
+      tone: 'danger',
+      state: {
+        disabled: false,
+        focused: false,
+        hovered: true,
+        pressed: false,
+      },
+    });
+
+    expect(solid.backgroundColor).toBe(theme.semantics.action.primary.base);
+    expect(solid.contentColor).toBe(theme.semantics.action.primary.onSolidText);
+    expect(outline.borderColor).toBe(theme.semantics.action.danger.outline);
+    expect(outline.backgroundColor).toBe(theme.semantics.action.danger.softHover);
+  });
+
+  it('derives input colors from interaction and validation state', () => {
+    const theme = createTheme();
+    const focusedInvalid = resolveInputColors(
+      theme,
+      resolveFieldState({
+        focused: true,
+        invalid: true,
+      }),
+    );
+    const readOnly = resolveInputColors(
+      theme,
+      resolveFieldState({
+        readOnly: true,
+      }),
+    );
+
+    expect(focusedInvalid.borderColor).toBe(theme.semantics.danger.base);
+    expect(readOnly.backgroundColor).toBe(theme.semantics.surface.subtle);
+    expect(readOnly.placeholderColor).toBe(theme.semantics.content.muted);
+  });
+});