@ankhorage/zora 7.0.0 → 8.0.0

package/src/features/avatar/adapters/inbound/Avatar.tsx

@@ -0,0 +1,147 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+import React from 'react';
+import { Image } from 'react-native';
+
+import type { ZoraColor } from '../../../../internal/recipes';
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { AvatarProps, AvatarShape, AvatarSize } from '../../../../types/avatar';
+import { Icon } from '../../../icon/public';
+import { Box } from '../../../layout/public';
+import { Text, type TextVariant } from '../../../typography/public';
+import { resolveAvatarInitials } from '../../utils/resolveAvatarInitials';
+/***
+ * Displays a user or entity avatar with image support and initials fallback.
+ */
+export const Avatar = withZoraThemeScope(AvatarInner);
+
+function resolveAvatarSize(size: AvatarSize): number {
+  switch (size) {
+    case 'xs':
+      return 24;
+    case 's':
+      return 32;
+    case 'l':
+      return 48;
+    case 'xl':
+      return 64;
+    case 'm':
+    default:
+      return 40;
+  }
+}
+
+function resolveRoleSemantics(theme: SurfaceTheme, color: ZoraColor): RoleSemantics {
+  switch (color) {
+    case 'secondary':
+      return theme.semantics.secondary;
+    case 'tertiary':
+      return theme.semantics.accent;
+    case 'quaternary':
+      return theme.semantics.highlight;
+    case 'primary':
+      return theme.semantics.action.primary;
+    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 'neutral':
+    default:
+      return theme.semantics.action.neutral;
+  }
+}
+
+function resolveTextColor(color: ZoraColor): ZoraColor | undefined {
+  return color === 'neutral' ? undefined : color;
+}
+
+function resolveTextVariant(size: AvatarSize): TextVariant {
+  switch (size) {
+    case 'xs':
+    case 's':
+      return 'caption';
+    case 'l':
+      return 'bodySmall';
+    case 'xl':
+      return 'lead';
+    case 'm':
+    default:
+      return 'label';
+  }
+}
+
+function resolveRadius(shape: AvatarShape): 'full' | 'l' {
+  return shape === 'circle' ? 'full' : 'l';
+}
+
+function AvatarInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  source,
+  name,
+  initials,
+  iconFallback,
+  label,
+  size = 'm',
+  shape = 'circle',
+  color = 'neutral',
+  interactionPolicy: _interactionPolicy,
+}: AvatarProps) {
+  const { theme } = useZoraTheme();
+  const resolvedSize = resolveAvatarSize(size);
+  const resolvedInitials = initials ?? resolveAvatarInitials(name);
+  const role = resolveRoleSemantics(theme, color);
+  const backgroundColor = color === 'neutral' ? theme.semantics.neutral.surface : role.softBg;
+  const contentColor = color === 'neutral' ? theme.semantics.content.default : role.base;
+  const radius = resolveRadius(shape);
+
+  const renderFallback = () => {
+    if (resolvedInitials) {
+      return (
+        <Text color={resolveTextColor(color)} variant={resolveTextVariant(size)} weight="semiBold">
+          {resolvedInitials}
+        </Text>
+      );
+    }
+
+    if (iconFallback) {
+      const iconSize = Math.max(16, Math.round(resolvedSize * 0.48));
+      return <Icon {...iconFallback} color={contentColor} size={iconSize} />;
+    }
+
+    return null;
+  };
+
+  return (
+    <Box
+      accessibilityLabel={label}
+      bg={backgroundColor}
+      height={resolvedSize}
+      radius={radius}
+      testID={testID}
+      width={resolvedSize}
+      style={{
+        alignItems: 'center',
+        justifyContent: 'center',
+        overflow: 'hidden',
+      }}
+    >
+      {source ? (
+        <Image
+          accessibilityLabel={label}
+          source={source}
+          style={{ height: '100%', width: '100%' }}
+        />
+      ) : (
+        renderFallback()
+      )}
+    </Box>
+  );
+}

package/src/features/avatar/adapters/inbound/AvatarGroup.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { AvatarGroupItem, AvatarGroupProps } from '../../../../types/avatar-group';
+import { Box, Stack } from '../../../layout/public';
+import { Avatar } from '../../public';
+/***
+ * Renders a compact group of avatars with optional overflow handling.
+ */
+export const AvatarGroup = withZoraThemeScope(AvatarGroupInner);
+
+function defaultOverflowLabel(overflowCount: number): string {
+  return `+${overflowCount}`;
+}
+
+function AvatarGroupInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  testID,
+  items,
+  max = 4,
+  size = 's',
+  shape = 'circle',
+  overflowLabel = defaultOverflowLabel,
+}: AvatarGroupProps) {
+  const { theme } = useZoraTheme();
+
+  const visibleItems = items.slice(0, max);
+  const overflowCount = Math.max(0, items.length - visibleItems.length);
+  const overlap =
+    size === 'xs' ? 8 : size === 's' ? 10 : size === 'm' ? 12 : size === 'l' ? 14 : 16;
+  const borderColor = theme.semantics.surface.default;
+
+  const renderItem = (item: AvatarGroupItem, index: number) => (
+    <Box
+      key={item.id ?? `${index}`}
+      ml={index === 0 ? 0 : -overlap}
+      radius="full"
+      borderWidth={2}
+      borderColor={borderColor}
+    >
+      <Avatar
+        iconFallback={item.iconFallback}
+        initials={item.initials}
+        label={item.label}
+        name={item.name}
+        shape={shape}
+        size={size}
+        source={item.source}
+        color={item.color}
+      />
+    </Box>
+  );
+
+  return (
+    <Stack align="center" direction="row" testID={testID} wrap="nowrap">
+      {visibleItems.map(renderItem)}
+      {overflowCount > 0 ? (
+        <Box
+          ml={visibleItems.length === 0 ? 0 : -overlap}
+          radius="full"
+          borderWidth={2}
+          borderColor={borderColor}
+        >
+          <Avatar
+            initials={overflowLabel(overflowCount)}
+            size={size}
+            shape={shape}
+            color="neutral"
+          />
+        </Box>
+      ) : null}
+    </Stack>
+  );
+}

package/src/features/avatar/avatarGroupMeta.ts

@@ -0,0 +1,25 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { avatarMeta } from './avatarMeta';
+
+export const avatarGroupMeta = {
+  name: 'AvatarGroup',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Avatar group', defaultProps: { items: [] } },
+  props: {
+    items: {
+      type: 'array',
+      category: 'Content',
+      itemSchema: [
+        { key: 'id', schema: { type: 'string', category: 'Identity' } },
+        ...Object.entries(avatarMeta.props)
+          .filter(([key]) => key !== 'size' && key !== 'shape')
+          .map(([key, schema]) => ({ key, schema })),
+      ],
+    },
+    max: { type: 'number', category: 'Layout' },
+    size: avatarMeta.props.size,
+    shape: avatarMeta.props.shape,
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/avatar/avatarMeta.ts

@@ -0,0 +1,42 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const avatarMeta = {
+  name: 'Avatar',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  props: {
+    source: {
+      type: 'media',
+      category: 'Content',
+      mediaKinds: ['image'],
+    },
+    name: {
+      type: 'string',
+      category: 'Content',
+    },
+    initials: {
+      type: 'string',
+      category: 'Content',
+    },
+    label: {
+      type: 'string',
+      category: 'Accessibility',
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['xs', 's', 'm', 'l', 'xl'],
+    },
+    shape: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['circle', 'rounded'],
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['primary', 'secondary', 'neutral', 'success', 'warning', 'danger', 'info'],
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/avatar/public.ts

@@ -0,0 +1,5 @@
+export type { AvatarProps, AvatarShape, AvatarSize } from '../../types/avatar';
+export type { AvatarGroupItem, AvatarGroupProps } from '../../types/avatar-group';
+export { Avatar } from './adapters/inbound/Avatar';
+export { AvatarGroup } from './adapters/inbound/AvatarGroup';
+export { resolveAvatarInitials } from './utils/resolveAvatarInitials';

package/src/features/badge/adapters/inbound/Badge.tsx

@@ -0,0 +1,33 @@
+import { Badge as SurfaceBadge } from '@ankhorage/surface';
+import React from 'react';
+
+import { resolveBadgeRecipe } from '../../../../internal/recipes';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { BadgeProps } from '../../../../types/badge';
+/***
+ * Shows a small status, label, or count indicator.
+ */
+export const Badge = withZoraThemeScope(BadgeInner);
+
+function BadgeInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  children,
+  color,
+  variant,
+  size,
+  ...props
+}: BadgeProps) {
+  const recipe = resolveBadgeRecipe({ color, variant, size });
+
+  return (
+    <SurfaceBadge
+      {...props}
+      content={children}
+      color={recipe.color}
+      size={recipe.size}
+      variant={recipe.variant}
+    />
+  );
+}

package/src/features/badge/badgeMeta.ts

@@ -0,0 +1,29 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const badgeMeta = {
+  name: 'Badge',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  props: {
+    children: {
+      type: 'string',
+      category: 'Content',
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['primary', 'secondary', 'neutral', 'success', 'warning', 'danger', 'info'],
+    },
+    variant: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['solid', 'soft', 'outline'],
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['s', 'm', 'l'],
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/badge/public.ts

@@ -0,0 +1,2 @@
+export type { BadgeProps } from '../../types/badge';
+export { Badge } from './adapters/inbound/Badge';

package/src/features/bottom-sheet/adapters/inbound/BottomSheet.tsx

@@ -0,0 +1,85 @@
+import { useBottomSheet } from '@ankhorage/surface/bottom-sheet';
+import React from 'react';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import { useZoraThemeRuntime } from '../../../../theme/ZoraThemeRuntimeContext';
+import type { BottomSheetProps } from '../../../../types/manifest-bottom-sheet';
+import { Box } from '../../../layout/public';
+
+/*** Presents declarative manifest children through the shared Surface sheet host. */
+export const BottomSheet = withZoraThemeScope(BottomSheetInner);
+
+/*** Bridges the declarative lifecycle and inherited theme into the shared modal host. */
+function BottomSheetInner({
+  mode: _mode,
+  themeId: _themeId,
+  children,
+  open = false,
+  interactionPolicy,
+  testID,
+  snapPoints,
+  initialIndex,
+  enableDynamicSizing,
+  enablePanDownToClose,
+  dismissOnBackdropPress,
+  keyboardBehavior,
+  keyboardBlurBehavior,
+  onDismiss,
+  onIndexChange,
+}: BottomSheetProps) {
+  const { present, dismiss } = useBottomSheet();
+  const { mode } = useZoraTheme();
+  const { themeId } = useZoraThemeRuntime();
+  const active = open && interactionPolicy !== 'passive';
+  const dismissed = React.useRef(false);
+
+  React.useEffect(() => {
+    dismissed.current = false;
+    if (!active) return;
+    return () => {
+      dismiss();
+    };
+  }, [active, dismiss]);
+
+  React.useEffect(() => {
+    if (!active || dismissed.current) return;
+    present({
+      content: (
+        <Box mode={mode} themeId={themeId} testID={testID}>
+          {children}
+        </Box>
+      ),
+      snapPoints,
+      initialIndex,
+      enableDynamicSizing,
+      enablePanDownToClose,
+      dismissOnBackdropPress,
+      keyboardBehavior,
+      keyboardBlurBehavior,
+      onDismiss: () => {
+        dismissed.current = true;
+        onDismiss?.();
+      },
+      onIndexChange: (index) => onIndexChange?.({ index }),
+    });
+  }, [
+    active,
+    children,
+    dismissOnBackdropPress,
+    enableDynamicSizing,
+    enablePanDownToClose,
+    initialIndex,
+    keyboardBehavior,
+    keyboardBlurBehavior,
+    mode,
+    onDismiss,
+    onIndexChange,
+    present,
+    snapPoints,
+    testID,
+    themeId,
+  ]);
+
+  return null;
+}

package/src/features/bottom-sheet/bottomSheetMeta.ts

@@ -0,0 +1,33 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const bottomSheetMeta = {
+  name: 'BottomSheet',
+  category: 'layout',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  description:
+    'Controlled presentation through the shared single-sheet host. Bind dismiss to clear open.',
+  events: {
+    dismiss: { label: 'Dismiss', eventType: 'bottomSheet.dismiss', payloadFields: [] },
+    indexChange: {
+      label: 'Index change',
+      eventType: 'bottomSheet.indexChange',
+      payloadFields: [{ path: 'index', type: 'number' }],
+    },
+  },
+  props: {
+    open: { type: 'boolean', category: 'State', default: false },
+    snapPoints: { type: 'array', category: 'Layout' },
+    initialIndex: { type: 'number', category: 'State' },
+    enableDynamicSizing: { type: 'boolean', category: 'Layout' },
+    enablePanDownToClose: { type: 'boolean', category: 'Behavior' },
+    dismissOnBackdropPress: { type: 'boolean', category: 'Behavior' },
+    keyboardBehavior: {
+      type: 'enum',
+      category: 'Behavior',
+      enum: ['extend', 'fillParent', 'interactive'],
+    },
+    keyboardBlurBehavior: { type: 'enum', category: 'Behavior', enum: ['none', 'restore'] },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/bottom-sheet/public.ts

@@ -1,3 +1,5 @@
+export type { BottomSheetProps } from '../../types/manifest-bottom-sheet';
+export { BottomSheet } from './adapters/inbound/BottomSheet';
 export type {
   BottomSheetController,
   BottomSheetPresentOptions,

package/src/features/button/adapters/inbound/Button.tsx

@@ -0,0 +1,42 @@
+import { Button as SurfaceButton } from '@ankhorage/surface';
+import React from 'react';
+
+import { useZoraThemeRecipe } from '../../../../theme/useZoraThemeRecipe';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ButtonProps } from '../../../../types/button';
+import { resolveButtonThemeRecipe } from '../../utils/resolveButtonThemeRecipe';
+/***
+ * Theme-aware action control for primary, secondary, destructive, and neutral actions.
+ *
+ * Use `Button` for explicit user actions that should follow ZORA's semantic color,
+ * variant, and size recipes across React Native and React Native Web.
+ *
+ * @example Basic action
+ * ```tsx
+ * <Button color="primary" variant="solid" onPress={save}>Save</Button>
+ * ```
+ */
+export const Button = withZoraThemeScope(ButtonInner);
+
+function ButtonInner({
+  themeId: _themeId,
+  mode: _mode,
+  color,
+  variant,
+  size,
+  interactionPolicy,
+  ...props
+}: ButtonProps) {
+  const themeFields = useZoraThemeRecipe('Button');
+  const recipe = resolveButtonThemeRecipe({ color, variant, size, themeFields });
+
+  return (
+    <SurfaceButton
+      {...props}
+      color={recipe.color}
+      size={recipe.size}
+      variant={recipe.variant}
+      interactionPolicy={interactionPolicy}
+    />
+  );
+}

package/src/features/button/adapters/inbound/ButtonGroup.tsx

@@ -0,0 +1,112 @@
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type {
+  ButtonGroupAlign,
+  ButtonGroupOrientation,
+  ButtonGroupProps,
+} from '../../../../types/button-group';
+import { Stack } from '../../../layout/public';
+/***
+ * Groups multiple `Button` elements with consistent spacing and alignment.
+ */
+export const ButtonGroup = withZoraThemeScope(ButtonGroupInner);
+
+function resolveDirection(orientation: ButtonGroupOrientation) {
+  if (orientation === 'vertical') {
+    return 'column';
+  }
+
+  if (orientation === 'responsive') {
+    return { base: 'column', md: 'row' } as const;
+  }
+
+  return 'row';
+}
+
+function resolveHorizontalJustify(align: ButtonGroupAlign) {
+  switch (align) {
+    case 'start':
+      return 'flex-start';
+    case 'center':
+      return 'center';
+    case 'between':
+      return 'space-between';
+    case 'stretch':
+    case 'end':
+    default:
+      return 'flex-end';
+  }
+}
+
+function resolveVerticalAlign(align: ButtonGroupAlign) {
+  switch (align) {
+    case 'start':
+      return 'flex-start';
+    case 'center':
+    case 'between':
+      return 'center';
+    case 'stretch':
+      return 'stretch';
+    case 'end':
+    default:
+      return 'flex-end';
+  }
+}
+
+function resolveStackAlign(align: ButtonGroupAlign, orientation: ButtonGroupOrientation) {
+  if (orientation === 'horizontal') {
+    return align === 'stretch' ? 'stretch' : 'center';
+  }
+
+  if (orientation === 'responsive') {
+    return {
+      base: resolveVerticalAlign(align),
+      md: align === 'stretch' ? 'stretch' : 'center',
+    } as const;
+  }
+
+  return resolveVerticalAlign(align);
+}
+
+function resolveStackJustify(align: ButtonGroupAlign, orientation: ButtonGroupOrientation) {
+  if (orientation === 'horizontal') {
+    return resolveHorizontalJustify(align);
+  }
+
+  if (orientation === 'responsive') {
+    return {
+      base: align === 'between' ? 'space-between' : 'flex-start',
+      md: resolveHorizontalJustify(align),
+    } as const;
+  }
+
+  return align === 'between' ? 'space-between' : 'flex-start';
+}
+
+function ButtonGroupInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  align = 'end',
+  orientation = 'horizontal',
+  gap = 's',
+  reverse = false,
+  testID,
+  interactionPolicy: _interactionPolicy,
+}: ButtonGroupProps) {
+  const items = React.Children.toArray(children);
+  const orderedItems = reverse ? items.reverse() : items;
+
+  return (
+    <Stack
+      align={resolveStackAlign(align, orientation)}
+      direction={resolveDirection(orientation)}
+      gap={gap}
+      justify={resolveStackJustify(align, orientation)}
+      testID={testID}
+    >
+      {orderedItems}
+    </Stack>
+  );
+}

package/src/features/button/adapters/inbound/IconButton.tsx

@@ -0,0 +1,37 @@
+import { IconButton as SurfaceIconButton } from '@ankhorage/surface';
+import React from 'react';
+
+import { resolveButtonRecipe } from '../../../../internal/recipes';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { IconButtonProps } from '../../../../types/icon-button';
+/***
+ * Icon-only button for compact actions; requires an accessible `label`.
+ */
+export const IconButton = withZoraThemeScope(IconButtonInner);
+
+function IconButtonInner({
+  themeId: _themeId,
+  mode: _mode,
+  icon,
+  iconName,
+  label,
+  variant = 'ghost',
+  color = 'neutral',
+  size = 'm',
+  interactionPolicy,
+  ...props
+}: IconButtonProps) {
+  const recipe = resolveButtonRecipe({ color, variant, size });
+
+  return (
+    <SurfaceIconButton
+      {...props}
+      icon={icon ?? { name: iconName ?? 'add' }}
+      accessibilityLabel={label}
+      color={recipe.color}
+      size={recipe.size}
+      variant={recipe.variant}
+      interactionPolicy={interactionPolicy}
+    />
+  );
+}