@ankhorage/surface 0.1.5 → 0.1.6

package/src/examples/DocsExamples.tsx

@@ -0,0 +1,116 @@
+import React from 'react';
+
+import {
+  Badge,
+  Box,
+  Button,
+  Checkbox,
+  Drawer,
+  Field,
+  HelperText,
+  Label,
+  Menu,
+  Modal,
+  Radio,
+  Stack,
+  Switch,
+  Tab,
+  TabList,
+  TabPanel,
+  Tabs,
+  Text,
+  Textarea,
+  TextInput,
+  ThemeProvider,
+} from '../index';
+
+const docsThemeConfig = {
+  id: 'docs-example',
+  name: 'Docs Example',
+  light: {
+    harmony: 'monochromatic' as const,
+    primaryColor: '#2563eb',
+    systemTone: 'neutral' as const,
+  },
+  dark: {
+    harmony: 'monochromatic' as const,
+    primaryColor: '#2563eb',
+    systemTone: 'neutral' as const,
+  },
+};
+
+export function ProviderExample() {
+  return (
+    <ThemeProvider initialConfig={docsThemeConfig}>
+      <Stack gap="m" p="l">
+        <Text variant="body">Surface starter</Text>
+        <Badge content="Foundation" tone="success" />
+        <Button tone="warning" variant="soft">
+          Continue
+        </Button>
+      </Stack>
+    </ThemeProvider>
+  );
+}
+
+export function FormAndOverlayExample() {
+  return (
+    <ThemeProvider initialConfig={docsThemeConfig}>
+      <Stack gap="m" p="l">
+        <Field helperText="We only use this for sign-in." label="Email">
+          <TextInput placeholder="name@example.com" />
+        </Field>
+        <Field errorText="Bio is required." invalid label="Bio">
+          <Textarea placeholder="Tell us a little about yourself" />
+        </Field>
+        <Stack gap="s">
+          <Label required>Preferences</Label>
+          <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>
+        </Stack>
+        <Modal visible={false}>
+          <Text>Modal content</Text>
+        </Modal>
+        <Drawer visible={false}>
+          <Text>Drawer content</Text>
+        </Drawer>
+      </Stack>
+    </ThemeProvider>
+  );
+}
+
+export function NavigationExample() {
+  return (
+    <ThemeProvider initialConfig={docsThemeConfig}>
+      <Stack gap="m" p="l">
+        <Tabs defaultValue="account">
+          <TabList>
+            <Tab value="account">Account</Tab>
+            <Tab disabled value="security">
+              Security
+            </Tab>
+            <Tab value="billing">Billing</Tab>
+          </TabList>
+          <TabPanel value="account">
+            <Text>Account settings</Text>
+          </TabPanel>
+          <TabPanel value="billing">
+            <Text>Billing settings</Text>
+          </TabPanel>
+        </Tabs>
+        <Menu
+          items={[
+            { id: 'edit', label: 'Edit' },
+            { disabled: true, id: 'archive', label: 'Archive' },
+          ]}
+          trigger={<Text>Open menu</Text>}
+        />
+        <Box>
+          <Text tone="success">Theme overrides can stay semantic.</Text>
+        </Box>
+      </Stack>
+    </ThemeProvider>
+  );
+}

package/src/index.test.ts

@@ -0,0 +1,64 @@
+import { readFileSync } from 'node:fs';
+
+import { describe, expect, it } from 'bun:test';
+
+const indexSource = readFileSync(new URL('./index.ts', import.meta.url), 'utf8');
+const packageJson = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+) as {
+  exports: Record<string, unknown>;
+  files: string[];
+};
+
+const expectedRootExports = [
+  "export { Badge } from './components/badge';",
+  "export { Button } from './components/button';",
+  "export { Card } from './components/card';",
+  "export { Checkbox } from './components/checkbox';",
+  "export { Drawer } from './components/drawer';",
+  "export { Field } from './components/field';",
+  "export { HelperText } from './components/helper-text';",
+  "export { IconButton } from './components/icon-button';",
+  "export { Label } from './components/label';",
+  "export { ListItem } from './components/list-item';",
+  "export { Menu } from './components/menu';",
+  "export { Modal } from './components/modal';",
+  "export { Radio } from './components/radio';",
+  "export { Switch } from './components/switch';",
+  "export { Tab, TabList, TabPanel, Tabs } from './components/tabs';",
+  "export { TextInput } from './components/text-input';",
+  "export { Textarea } from './components/textarea';",
+  "export { Toast, ToastProvider, useToast } from './components/toast';",
+  "export { Tooltip } from './components/tooltip';",
+  "export * from './core/responsive';",
+  "export * from './layout';",
+  "export * from './theme';",
+] as const;
+
+describe('public package contract', () => {
+  it('keeps the intended package surface on the root barrel', () => {
+    expectedRootExports.forEach((line) => {
+      expect(indexSource).toContain(line);
+    });
+  });
+
+  it('keeps internal infrastructure off the public barrel', () => {
+    expect(indexSource).not.toContain("'./internal/");
+    expect(indexSource).not.toContain('resolveSelectionControlNextChecked');
+    expect(indexSource).not.toContain('resolveFieldPresentation');
+    expect(indexSource).not.toContain('FocusScope');
+    expect(indexSource).not.toContain('useFocusManager');
+  });
+
+  it('keeps package metadata aligned with the single-entry public surface', () => {
+    expect(packageJson.files).toEqual(['dist', 'README.md', 'CHANGELOG.md', 'LICENSE']);
+    expect(packageJson.exports).toEqual({
+      '.': {
+        default: './dist/index.js',
+        import: './dist/index.js',
+        types: './dist/index.d.ts',
+      },
+      './package.json': './package.json',
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,55 @@
+export type { BadgeProps } from './components/badge';
+export { Badge } from './components/badge';
+export type { ButtonIconSpec, ButtonProps } from './components/button';
+export { Button } from './components/button';
+export type { CardProps } from './components/card';
+export { Card } from './components/card';
+export type { CheckboxProps } from './components/checkbox';
+export { Checkbox } from './components/checkbox';
+export type { DrawerProps } from './components/drawer';
+export { Drawer } from './components/drawer';
+export type { FieldProps } from './components/field';
+export { Field } from './components/field';
+export type { HelperTextProps } from './components/helper-text';
+export { HelperText } from './components/helper-text';
+export type { IconButtonProps } from './components/icon-button';
+export { IconButton } from './components/icon-button';
+export type { LabelProps } from './components/label';
+export { Label } from './components/label';
+export type { ListItemProps } from './components/list-item';
+export { ListItem } from './components/list-item';
+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 { RadioProps } from './components/radio';
+export { Radio } from './components/radio';
+export type { SwitchProps } from './components/switch';
+export { Switch } from './components/switch';
+export type { TabListProps, TabPanelProps, TabProps, TabsProps } from './components/tabs';
+export { Tab, TabList, TabPanel, Tabs } from './components/tabs';
+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 { Toast, ToastProvider, useToast } from './components/toast';
+export type { TooltipProps } from './components/tooltip';
+export { Tooltip } from './components/tooltip';
+export type { FontRuntime } from './context/FontContext';
+export { FontProvider, useFontContext } from './context/FontContext';
+export type { I18nInstance, TranslationRuntime, Translator } from './context/TranslationContext';
+export { TranslationProvider, useTranslationContext } from './context/TranslationContext';
+export * from './core/responsive';
+export * from './layout';
+export type { ButtonBaseProps } from './primitives/button-base';
+export { ButtonBase } from './primitives/button-base';
+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 { TextProps } from './primitives/text';
+export { Text } from './primitives/text';
+export * from './theme';
+export { isDeepEqual } from './utils/deepEqual';
+export { deepMerge } from './utils/deepMerge';

package/src/internal/focus/FocusScope.tsx

@@ -0,0 +1,66 @@
+import React from 'react';
+import { View } from 'react-native';
+
+import { useFocusManager } from './useFocusManager';
+
+export interface FocusScopeProps {
+  active: boolean;
+  children?: React.ReactNode;
+  onEscape?: (() => void) | undefined;
+  testID?: string;
+}
+
+export function FocusScope({ active, children, onEscape, testID }: FocusScopeProps) {
+  const containerRef = React.useRef<View | null>(null);
+  const { bindKeydown, capturePreviousFocus, cycleFocus, focusFirst, restorePreviousFocus } =
+    useFocusManager();
+
+  React.useEffect(() => {
+    if (!active) {
+      return undefined;
+    }
+
+    capturePreviousFocus();
+    const timeoutId = setTimeout(() => {
+      focusFirst(containerRef.current);
+    }, 0);
+
+    const unbind = bindKeydown((event) => {
+      if (event.key === 'Tab') {
+        event.preventDefault();
+        cycleFocus(containerRef.current, Boolean(event.shiftKey));
+      }
+
+      if (event.key === 'Escape') {
+        onEscape?.();
+      }
+    });
+
+    return () => {
+      clearTimeout(timeoutId);
+      unbind();
+      restorePreviousFocus();
+    };
+  }, [
+    active,
+    bindKeydown,
+    capturePreviousFocus,
+    cycleFocus,
+    focusFirst,
+    onEscape,
+    restorePreviousFocus,
+  ]);
+
+  return (
+    <View
+      collapsable={false}
+      ref={containerRef}
+      testID={testID}
+      style={{
+        flex: 1,
+      }}
+    >
+      {children}
+    </View>
+  );
+}

package/src/internal/focus/useFocusManager.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'bun:test';
+
+import { getFocusableElements } from './useFocusManager';
+
+interface MockFocusableTarget {
+  disabled?: boolean;
+  focus: () => void;
+  getAttribute?: (name: string) => string | null;
+  hidden?: boolean;
+  tabIndex?: number;
+}
+
+describe('getFocusableElements', () => {
+  it('filters disabled, hidden, and aria-hidden nodes from focus traps', () => {
+    const active: MockFocusableTarget = {
+      focus: () => undefined,
+      getAttribute: () => null,
+    };
+    const disabled: MockFocusableTarget = {
+      disabled: true,
+      focus: () => undefined,
+      getAttribute: () => null,
+    };
+    const ariaHidden: MockFocusableTarget = {
+      focus: () => undefined,
+      getAttribute: (name) => (name === 'aria-hidden' ? 'true' : null),
+    };
+    const untabbable: MockFocusableTarget = {
+      focus: () => undefined,
+      getAttribute: (name) => (name === 'tabindex' ? '-1' : null),
+    };
+
+    const container = {
+      querySelectorAll: () => [active, disabled, ariaHidden, untabbable],
+    };
+
+    expect(getFocusableElements(container)).toEqual([active]);
+  });
+
+  it('returns an empty list when no DOM-like query API is available', () => {
+    expect(getFocusableElements(null)).toEqual([]);
+    expect(getFocusableElements({})).toEqual([]);
+  });
+});

package/src/internal/focus/useFocusManager.ts

@@ -0,0 +1,142 @@
+import React from 'react';
+
+interface FocusableTarget {
+  focus: () => void;
+  disabled?: boolean;
+  hidden?: boolean;
+  tabIndex?: number;
+  getAttribute?: (name: string) => string | null;
+}
+
+interface FocusContainer {
+  contains: (node: unknown) => boolean;
+  querySelectorAll: (selector: string) => ArrayLike<FocusableTarget>;
+}
+
+interface WebKeyboardEventLike {
+  key?: string;
+  preventDefault: () => void;
+  shiftKey?: boolean;
+}
+
+interface WebDocumentLike {
+  activeElement: unknown;
+  addEventListener: (type: 'keydown', listener: (event: WebKeyboardEventLike) => void) => void;
+  removeEventListener: (type: 'keydown', listener: (event: WebKeyboardEventLike) => void) => void;
+}
+
+const FOCUSABLE_SELECTOR = 'button,[href],input,select,textarea,[tabindex]:not([tabindex="-1"])';
+
+function getWebDocument(): WebDocumentLike | null {
+  const maybeDocument = (globalThis as { document?: unknown }).document;
+
+  if (!maybeDocument || typeof maybeDocument !== 'object') {
+    return null;
+  }
+
+  return maybeDocument as WebDocumentLike;
+}
+
+function isFocusableTarget(target: FocusableTarget): boolean {
+  if (target.disabled || target.hidden) {
+    return false;
+  }
+
+  if (typeof target.tabIndex === 'number' && target.tabIndex < 0) {
+    return false;
+  }
+
+  const ariaHidden = target.getAttribute?.('aria-hidden');
+  if (ariaHidden === 'true') {
+    return false;
+  }
+
+  const tabIndexAttribute = target.getAttribute?.('tabindex');
+  if (tabIndexAttribute === '-1') {
+    return false;
+  }
+
+  return true;
+}
+
+export function getFocusableElements(container: unknown): FocusableTarget[] {
+  if (!container || typeof container !== 'object') {
+    return [];
+  }
+
+  const focusContainer = container as FocusContainer;
+  if (typeof focusContainer.querySelectorAll !== 'function') {
+    return [];
+  }
+
+  return Array.from(focusContainer.querySelectorAll(FOCUSABLE_SELECTOR)).filter(isFocusableTarget);
+}
+
+export function useFocusManager() {
+  const previousFocusRef = React.useRef<FocusableTarget | null>(null);
+
+  const capturePreviousFocus = React.useCallback(() => {
+    const documentRef = getWebDocument();
+    const activeElement = documentRef?.activeElement;
+
+    previousFocusRef.current =
+      activeElement && typeof activeElement === 'object' && 'focus' in activeElement
+        ? (activeElement as FocusableTarget)
+        : null;
+  }, []);
+
+  const focusFirst = React.useCallback((container: unknown) => {
+    const [firstFocusable] = getFocusableElements(container);
+
+    firstFocusable?.focus();
+  }, []);
+
+  const restorePreviousFocus = React.useCallback(() => {
+    previousFocusRef.current?.focus();
+  }, []);
+
+  const cycleFocus = React.useCallback((container: unknown, reverse = false) => {
+    const focusableElements = getFocusableElements(container);
+    if (focusableElements.length === 0) {
+      return;
+    }
+
+    const documentRef = getWebDocument();
+    const activeElement = documentRef?.activeElement;
+    const currentIndex = focusableElements.findIndex((element) => element === activeElement);
+
+    if (currentIndex === -1) {
+      (reverse ? focusableElements[focusableElements.length - 1] : focusableElements[0])?.focus();
+      return;
+    }
+
+    const nextIndex = reverse
+      ? (currentIndex - 1 + focusableElements.length) % focusableElements.length
+      : (currentIndex + 1) % focusableElements.length;
+
+    focusableElements[nextIndex]?.focus();
+  }, []);
+
+  const bindKeydown = React.useCallback((listener: (event: WebKeyboardEventLike) => void) => {
+    const documentRef = getWebDocument();
+    if (!documentRef) {
+      return () => {
+        /* no-op */
+      };
+    }
+
+    documentRef.addEventListener('keydown', listener);
+
+    return () => {
+      documentRef.removeEventListener('keydown', listener);
+    };
+  }, []);
+
+  return {
+    bindKeydown,
+    capturePreviousFocus,
+    cycleFocus,
+    focusFirst,
+    restorePreviousFocus,
+  };
+}

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),
+  };
+}