@ankhorage/zora 14.0.1 → 16.0.0

package/dist/types/tabs.d.ts

@@ -0,0 +1,21 @@
+import type React from 'react';
+import type { ZoraBaseProps } from '../theme/ZoraBaseProps';
+export interface TabsProps extends ZoraBaseProps {
+    children?: React.ReactNode;
+    value?: string;
+    defaultValue?: string;
+    onValueChange?: (value: string) => void;
+}
+export interface TabListProps extends ZoraBaseProps {
+    children?: React.ReactNode;
+}
+export interface TabProps extends ZoraBaseProps {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+export interface TabPanelProps extends ZoraBaseProps {
+    value: string;
+    children?: React.ReactNode;
+}
+//# sourceMappingURL=tabs.d.ts.map

package/dist/types/tabs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.d.ts","sourceRoot":"","sources":["../../src/types/tabs.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,MAAM,WAAW,SAAU,SAAQ,aAAa;IAC9C,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B;AAED,MAAM,WAAW,QAAS,SAAQ,aAAa;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,aAAc,SAAQ,aAAa;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC5B"}

package/dist/types/tabs.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tabs.js.map

package/dist/types/tabs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs.js","sourceRoot":"","sources":["../../src/types/tabs.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nimport type { ZoraBaseProps } from '../theme/ZoraBaseProps';\n\nexport interface TabsProps extends ZoraBaseProps {\n  children?: React.ReactNode;\n  value?: string;\n  defaultValue?: string;\n  onValueChange?: (value: string) => void;\n}\n\nexport interface TabListProps extends ZoraBaseProps {\n  children?: React.ReactNode;\n}\n\nexport interface TabProps extends ZoraBaseProps {\n  value: string;\n  label: string;\n  disabled?: boolean;\n}\n\nexport interface TabPanelProps extends ZoraBaseProps {\n  value: string;\n  children?: React.ReactNode;\n}\n"]}

package/dist/types/toolbar.d.ts

@@ -0,0 +1,8 @@
+import type React from 'react';
+import type { ZoraBaseProps } from '../theme/ZoraBaseProps';
+export interface ToolbarProps extends ZoraBaseProps {
+    children?: React.ReactNode;
+    floating?: boolean;
+    compact?: boolean;
+}
+//# sourceMappingURL=toolbar.d.ts.map

package/dist/types/toolbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar.d.ts","sourceRoot":"","sources":["../../src/types/toolbar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/types/toolbar.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=toolbar.js.map

package/dist/types/toolbar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbar.js","sourceRoot":"","sources":["../../src/types/toolbar.ts"],"names":[],"mappings":"","sourcesContent":["import type React from 'react';\n\nimport type { ZoraBaseProps } from '../theme/ZoraBaseProps';\n\nexport interface ToolbarProps extends ZoraBaseProps {\n  children?: React.ReactNode;\n  floating?: boolean;\n  compact?: boolean;\n}\n"]}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "14.0.1",
+  "version": "16.0.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -25,7 +25,6 @@
     "components"
   ],
   "peerDependencies": {
-    "@react-native-picker/picker": "2.11.4",
     "@react-native-vector-icons/fontawesome": "^13.1.3",
     "@react-native-vector-icons/fontawesome5": "^13.1.3",
     "@react-native-vector-icons/fontawesome6": "^13.1.3",
@@ -42,7 +41,7 @@
   "dependencies": {
     "@ankhorage/color-theory": "^0.3.0",
     "@ankhorage/contracts": "^12.0.1",
-    "@ankhorage/surface": "^4.4.0",
+    "@ankhorage/surface": "^5.0.0",
     "@ankhorage/utility": "^0.8.0",
     "expo-document-picker": "~57.0.1",
     "expo-image-picker": "~57.0.16"
@@ -117,7 +116,6 @@
   "devDependencies": {
     "@ankhorage/devtools": "^1.13.0",
     "@ankhorage/paradox": "^0.1.24",
-    "@react-native-picker/picker": "2.11.4",
     "@react-native-vector-icons/fontawesome": "^13.1.3",
     "@react-native-vector-icons/fontawesome5": "^13.1.3",
     "@react-native-vector-icons/fontawesome6": "^13.1.3",

package/src/audit.test.ts

@@ -120,62 +120,23 @@ describe('Plan 5 audit — no showcase bridge or direct Surface imports in examp
 
 describe('Plan 5 audit — product-facing src imports ZORA foundation, not Surface directly', () => {
   /**
-   * Components, layouts, and patterns that compose ZORA primitives should import
-   * foundation primitives from the local ZORA foundation layer, not directly
-   * from @ankhorage/surface.
-   *
-   * Foundation wrappers, theme infrastructure, internal recipes, and explicit
-   * Surface-wrapping boundary components are exempt.
+   * Features, layouts, and patterns that compose ZORA primitives should import
+   * foundation primitives from ZORA, not directly from @ankhorage/surface.
+   * The feature-owned layout adapters are the deliberate Surface foundation boundary.
    */
-  const EXEMPT_PATHS = new Set([
-    // Foundation wrappers — they ARE the Surface abstraction layer.
-    join(SRC_ROOT, 'foundation'),
-    // Theme infrastructure legitimately integrates with Surface theme/runtime types.
-    join(SRC_ROOT, 'theme'),
-    // Internal recipes may consume SurfaceTheme types as the typed recipe boundary.
-    join(SRC_ROOT, 'internal'),
-    // Explicit Surface primitive wrappers.
-    join(SRC_ROOT, 'components', 'checkbox', 'Checkbox.tsx'),
-    join(SRC_ROOT, 'features', 'icon', 'adapters', 'inbound', 'Icon.tsx'),
-    join(SRC_ROOT, 'features', 'button', 'adapters', 'inbound', 'IconButton.tsx'),
-    join(SRC_ROOT, 'components', 'modal', 'Modal.tsx'),
-    join(SRC_ROOT, 'features', 'form', 'text-input', 'adapters', 'inbound', 'TextInput.tsx'),
-    join(SRC_ROOT, 'features', 'typography', 'adapters', 'inbound', 'Text.tsx'),
-    join(SRC_ROOT, 'features', 'form', 'adapters', 'inbound', 'FormField.tsx'),
-    // Type-only imports that intentionally expose Surface-compatible prop specs.
-    join(SRC_ROOT, 'components', 'checkbox', 'types.ts'),
-    join(SRC_ROOT, 'types', 'form.ts'),
-    join(SRC_ROOT, 'types', 'icon-button.ts'),
-    join(SRC_ROOT, 'components', 'tabs', 'types.ts'),
-    join(SRC_ROOT, 'types', 'text.ts'),
-    join(SRC_ROOT, 'components', 'textarea', 'types.ts'),
-    join(SRC_ROOT, 'components', 'toolbar', 'types.ts'),
-    join(SRC_ROOT, 'patterns', 'tile-grid', 'types.ts'),
-  ]);
-
-  function isExempt(filePath: string): boolean {
-    for (const exemptPath of EXEMPT_PATHS) {
-      if (isPathWithin(filePath, exemptPath)) {
-        return true;
-      }
-    }
-
-    return false;
-  }
-
+  const SURFACE_FOUNDATION_BOUNDARY = join(SRC_ROOT, 'features', 'layout');
   const PRODUCT_FACING_DIRS = [
-    join(SRC_ROOT, 'components'),
+    join(SRC_ROOT, 'features'),
     join(SRC_ROOT, 'layout'),
     join(SRC_ROOT, 'patterns'),
   ];
-
   const FOUNDATION_PRIMITIVES_PATTERN =
     /import \{[^}]*\b(Box|Stack|Center|Container|Grid|Inline|Spacer|Divider)\b[^}]*\} from '@ankhorage\/surface'/;
 
-  test('component, layout, and pattern files do not import foundation primitives directly from @ankhorage/surface', () => {
+  test('feature, layout, and pattern files do not import foundation primitives directly from @ankhorage/surface', () => {
     for (const dir of PRODUCT_FACING_DIRS) {
       for (const filePath of listFiles(dir)) {
-        if (isExempt(filePath)) continue;
+        if (isPathWithin(filePath, SURFACE_FOUNDATION_BOUNDARY)) continue;
 
         const source = readFileSync(filePath, 'utf8');
         const match = FOUNDATION_PRIMITIVES_PATTERN.exec(source);
@@ -183,7 +144,7 @@ describe('Plan 5 audit — product-facing src imports ZORA foundation, not Surfa
         expect(
           match,
           `${filePath} imports Surface foundation primitive '${match?.[1]}' directly. ` +
-            `Use the ZORA foundation import ('../../foundation') instead.`,
+            'Use the feature-owned ZORA layout/foundation API instead.',
         ).toBeNull();
       }
     }

package/src/constants.ts

@@ -20,6 +20,7 @@ export const FEATURE_MANIFEST_ELEMENTS = {
   chip: ['Chip', 'ChipGroup'],
   'data-table': ['DataTable'],
   'date-picker': ['DatePicker'],
+  dialog: ['Dialog'],
   form: ['Form', 'FormError', 'FormField'],
   gradient: ['Gradient'],
   button: ['Button', 'IconButton', 'ButtonGroup'],
@@ -28,7 +29,11 @@ export const FEATURE_MANIFEST_ELEMENTS = {
   'keyboard-avoiding-view': ['KeyboardAvoidingView'],
   layout: ['Box', 'Container', 'ContentRail', 'Divider', 'Grid', 'Stack'],
   list: ['FlatList', 'SectionList'],
+  pagination: ['Pagination'],
+  rating: ['Rating'],
   skeleton: ['Skeleton', 'SkeletonCard', 'SkeletonList', 'SkeletonText'],
+  tabs: ['Tabs', 'TabList', 'Tab', 'TabPanel'],
+  toolbar: ['Toolbar'],
   typography: ['Heading', 'Text'],
   'time-picker': ['TimePicker'],
   uploader: ['Uploader'],

package/src/featureManifest.test.ts

@@ -12,13 +12,19 @@ test('every selected feature element is directly authorable through its canonica
     const source = await Bun.file(`src/features/${family}/public.ts`).text();
     for (const name of names) {
       const meta = catalog.get(name);
+      const hasAuthorableShape =
+        Object.keys(meta?.props ?? {}).length > 0 || (meta?.allowedChildren.length ?? 0) > 0;
       expect(meta?.directManifestNode, name).toBe(true);
-      expect(Object.keys(meta?.props ?? {}).length, name).toBeGreaterThan(0);
+      expect(hasAuthorableShape, name).toBe(true);
       expect(source, name).toContain(name);
     }
   }
 });
 
+test('feature ownership has no remaining legacy components directory', () => {
+  expect(existsSync('src/components')).toBe(false);
+});
+
 test('form composition has one canonical feature owner', () => {
   expect(existsSync('src/components/form')).toBe(false);
   expect(existsSync('src/patterns/form-field')).toBe(false);
@@ -38,7 +44,7 @@ test('migrated picker and presentation elements have one canonical feature owner
   }
 });
 
-test('interactive authoring retains state and event payload bindings after plugin composition', () => {
+test('existing interactive authoring retains bindings after plugin composition', () => {
   const meta = ZORA_CORE_PLUGIN_METADATA.componentMeta;
   expect(meta.DataTable?.bindings?.props?.sort?.value.type).toBe('object');
   expect(meta.DataTable?.bindings?.props?.rows?.value.type).toBe('array');
@@ -48,6 +54,29 @@ test('interactive authoring retains state and event payload bindings after plugi
     type: 'object',
   });
   expect(meta.BottomSheet?.bindings?.props?.open?.value.type).toBe('boolean');
+});
+
+test('final ownership data components retain bindings after plugin composition', () => {
+  const meta = ZORA_CORE_PLUGIN_METADATA.componentMeta;
+  expect(meta.Dialog?.bindings?.props?.visible?.value.type).toBe('boolean');
+  expect(meta.Dialog?.bindings?.events?.dismiss?.payload?.eventType).toBe('dialog.dismiss');
+  expect(meta.Pagination?.bindings?.props?.page?.value.type).toBe('number');
+  expect(meta.Pagination?.bindings?.events?.pageChange?.payload?.eventType).toBe(
+    'pagination.pageChange',
+  );
+  expect(meta.Rating?.bindings?.props?.value?.value.type).toBe('number');
+});
+
+test('final ownership form and tab components retain bindings after plugin composition', () => {
+  const meta = ZORA_CORE_PLUGIN_METADATA.componentMeta;
+  expect(meta.SearchInput?.bindings?.props?.value?.value.type).toBe('string');
+  expect(meta.SearchInput?.bindings?.events?.submit?.payload?.eventType).toBe('searchInput.submit');
+  expect(meta.Tabs?.bindings?.props?.value?.value.type).toBe('string');
+  expect(meta.Tabs?.bindings?.events?.valueChange?.payload?.eventType).toBe('tabs.valueChange');
+});
+
+test('existing scalar authoring bindings remain available after plugin composition', () => {
+  const meta = ZORA_CORE_PLUGIN_METADATA.componentMeta;
   expect(meta.Heading?.bindings?.props?.level?.value.type).toBe('number');
   expect(meta.Image?.bindings?.props?.radius?.value.type).toBe('unknown');
 });

package/src/features/app-bar/adapters/inbound/AppBar.tsx

@@ -4,35 +4,15 @@ import React from 'react';
 import { Inline } from '../../../../foundation';
 import { useZoraTheme } from '../../../../theme/useZoraTheme';
 import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
-import type { AppBarMode, AppBarOverflowAction, AppBarProps } from '../../../../types/app-bar';
+import type { AppBarMode, AppBarOverflowMenu, AppBarProps } from '../../../../types/app-bar';
 import { IconButton } from '../../../button/public';
 import { Box, Stack } from '../../../layout/public';
+import { PopoverMenu } from '../../../popover-menu/public';
 import { Heading, Text } from '../../../typography/public';
 
 const DEFAULT_CANCEL_ICON = { name: 'close-outline' } satisfies ButtonIconSpec;
 const DEFAULT_OVERFLOW_ICON = { name: 'ellipsis-vertical' } satisfies ButtonIconSpec;
 
-/*** Resolves the effective AppBar mode. */
-function resolveMode(mode: AppBarMode | undefined): AppBarMode {
-  return mode ?? { type: 'default' };
-}
-
-/*** Formats the active selection label with its optional count. */
-function resolveSelectionLabel({ count, label }: { count?: number; label: string }): string {
-  if (count === undefined) return label;
-  return `${label} (${count})`;
-}
-
-/*** Resolves the accessible label for the overflow action. */
-function resolveOverflowLabel(overflow: AppBarOverflowAction): string {
-  return overflow.label ?? 'More options';
-}
-
-/*** Resolves the accessible label for leaving selection mode. */
-function resolveCancelLabel(mode: Extract<AppBarMode, { type: 'selection' }>): string {
-  return mode.cancelLabel ?? 'Cancel selection';
-}
-
 /*** Renders a top app bar with title/subtitle and optional leading/trailing actions. */
 export const AppBar = withZoraThemeScope(AppBarInner);
 
@@ -56,8 +36,8 @@ function AppBarInner({
   const resolvedMode = resolveMode(appMode);
   const isSelectionMode = resolvedMode.type === 'selection';
   const resolvedLeading = leading ?? resolveSelectionLeading(resolvedMode, interactionPolicy);
-  const overflowButton = resolveOverflowButton(overflow, interactionPolicy);
-  const resolvedTrailing = resolveTrailing(actions, overflowButton);
+  const overflowMenu = resolveOverflowMenu(overflow, interactionPolicy, testID);
+  const resolvedTrailing = resolveTrailing(actions, overflowMenu);
   const resolvedCenter = resolveCenter({
     children,
     isSelectionMode,
@@ -80,6 +60,27 @@ function AppBarInner({
   );
 }
 
+/*** Resolves the effective AppBar mode. */
+function resolveMode(mode: AppBarMode | undefined): AppBarMode {
+  return mode ?? { type: 'default' };
+}
+
+/*** Formats the active selection label with its optional count. */
+function resolveSelectionLabel({ count, label }: { count?: number; label: string }): string {
+  if (count === undefined) return label;
+  return `${label} (${count})`;
+}
+
+/*** Resolves the accessible label for the overflow menu trigger. */
+function resolveOverflowLabel(overflow: AppBarOverflowMenu): string {
+  return overflow.label ?? 'More options';
+}
+
+/*** Resolves the accessible label for leaving selection mode. */
+function resolveCancelLabel(mode: Extract<AppBarMode, { type: 'selection' }>): string {
+  return mode.cancelLabel ?? 'Cancel selection';
+}
+
 /*** Resolves the selection action shown at the leading edge. */
 function resolveSelectionLeading(
   mode: AppBarMode,
@@ -100,37 +101,44 @@ function resolveSelectionLeading(
   );
 }
 
-/*** Resolves the optional overflow action. */
-function resolveOverflowButton(
-  overflow: AppBarOverflowAction | undefined,
+/*** Resolves the optional AppBar overflow action menu. */
+function resolveOverflowMenu(
+  overflow: AppBarOverflowMenu | undefined,
   interactionPolicy: AppBarProps['interactionPolicy'],
+  testID: string | undefined,
 ): React.ReactNode {
-  if (!overflow?.onPress) return null;
+  if (overflow === undefined || overflow.actions.length === 0) return null;
 
   return (
-    <IconButton
-      color="neutral"
-      disabled={overflow.disabled}
-      icon={overflow.icon ?? DEFAULT_OVERFLOW_ICON}
+    <PopoverMenu
+      actions={overflow.actions}
+      closeOnSelect={overflow.closeOnSelect}
       interactionPolicy={interactionPolicy}
-      label={resolveOverflowLabel(overflow)}
-      onPress={overflow.onPress}
-      size="m"
-      variant="ghost"
+      onDismiss={overflow.onDismiss}
+      testID={testID ? `${testID}-overflow` : undefined}
+      trigger={({ toggle }) => (
+        <IconButton
+          color="neutral"
+          disabled={overflow.disabled}
+          icon={overflow.icon ?? DEFAULT_OVERFLOW_ICON}
+          interactionPolicy={interactionPolicy}
+          label={resolveOverflowLabel(overflow)}
+          onPress={toggle}
+          size="m"
+          variant="ghost"
+        />
+      )}
     />
   );
 }
 
 /*** Composes trailing actions and overflow controls. */
-function resolveTrailing(
-  actions: React.ReactNode,
-  overflowButton: React.ReactNode,
-): React.ReactNode {
-  if (!actions && !overflowButton) return undefined;
+function resolveTrailing(actions: React.ReactNode, overflowMenu: React.ReactNode): React.ReactNode {
+  if (!actions && !overflowMenu) return undefined;
   return (
     <Inline align="center" gap="s" wrap="nowrap">
       {actions}
-      {overflowButton}
+      {overflowMenu}
     </Inline>
   );
 }

package/src/features/app-bar/public.ts

@@ -1,2 +1,2 @@
-export type { AppBarMode, AppBarOverflowAction, AppBarProps } from '../../types/app-bar';
+export type { AppBarMode, AppBarOverflowMenu, AppBarProps } from '../../types/app-bar';
 export { AppBar } from './adapters/inbound/AppBar';

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

@@ -10,8 +10,17 @@ describe('ZORA BottomSheet public contract', () => {
     const source = await Bun.file('src/features/bottom-sheet/public.ts').text();
 
     expect(packageJson.exports['./bottom-sheet']).toBeDefined();
-    expect(packageJson.dependencies['@ankhorage/surface']).toMatch(/^\^4\./u);
+    expect(packageJson.dependencies['@ankhorage/surface']).toMatch(/^\^5\./u);
     expect(source).toContain("from '@ankhorage/surface/bottom-sheet'");
+    for (const name of [
+      'BottomSheetFlatList',
+      'BottomSheetScrollView',
+      'BottomSheetSectionList',
+      'BottomSheetView',
+      'BottomSheetVirtualizedList',
+    ]) {
+      expect(source).toContain(name);
+    }
     const {
       'react-native-gesture-handler': gestureHandlerPeer,
       'react-native-reanimated': reanimatedPeer,

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

@@ -1,7 +1,15 @@
 export type { BottomSheetProps } from '../../types/manifest-bottom-sheet';
 export { BottomSheet } from './adapters/inbound/BottomSheet';
 export type {
+  BottomSheetContentMode,
   BottomSheetController,
   BottomSheetPresentOptions,
 } from '@ankhorage/surface/bottom-sheet';
-export { useBottomSheet } from '@ankhorage/surface/bottom-sheet';
+export {
+  BottomSheetFlatList,
+  BottomSheetScrollView,
+  BottomSheetSectionList,
+  BottomSheetView,
+  BottomSheetVirtualizedList,
+  useBottomSheet,
+} from '@ankhorage/surface/bottom-sheet';

package/src/features/breadcrumbs/adapters/inbound/Breadcrumbs.tsx

@@ -0,0 +1,179 @@
+import React from 'react';
+
+import { Inline } from '../../../../foundation';
+import { resolveIconSize } from '../../../../internal/recipes';
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type {
+  BreadcrumbItem,
+  BreadcrumbPressEvent,
+  BreadcrumbsProps,
+} from '../../../../types/breadcrumbs';
+import { Button } from '../../../button/public';
+import { Icon } from '../../../icon/public';
+import { Text } from '../../../typography/public';
+
+/*** Renders a breadcrumb trail whose final item represents the current location. */
+export const Breadcrumbs = withZoraThemeScope(BreadcrumbsInner);
+
+type BreadcrumbRenderItem =
+  | {
+      item: BreadcrumbItem;
+      type: 'item';
+    }
+  | {
+      type: 'ellipsis';
+    };
+
+/*** Connects serializable breadcrumb items to the component-level item press event. */
+function BreadcrumbsInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy,
+  items,
+  separator = '/',
+  maxItems,
+  compact = false,
+  disabled = false,
+  onItemPress,
+  testID,
+}: BreadcrumbsProps) {
+  const normalizedMaxItems = normalizeMaxItems(maxItems);
+  const renderItems = createRenderItems(items, normalizedMaxItems);
+  const currentItemId = items.at(-1)?.id;
+
+  if (items.length === 0) return null;
+
+  return (
+    <Inline align="center" gap={compact ? 'xs' : 's'} testID={testID} wrap="wrap">
+      {renderItems.map((renderItem, index) => {
+        const showSeparator = index !== renderItems.length - 1;
+
+        if (renderItem.type === 'ellipsis') {
+          return (
+            <React.Fragment key="ellipsis">
+              <Text emphasis="muted" variant={compact ? 'caption' : 'bodySmall'}>
+                …
+              </Text>
+              {showSeparator ? renderSeparator(separator) : null}
+            </React.Fragment>
+          );
+        }
+
+        return (
+          <BreadcrumbItemView
+            compact={compact}
+            current={renderItem.item.id === currentItemId}
+            disabled={disabled}
+            interactionPolicy={interactionPolicy}
+            item={renderItem.item}
+            key={renderItem.item.id}
+            onItemPress={onItemPress}
+            separator={showSeparator ? separator : undefined}
+            testID={testID}
+          />
+        );
+      })}
+    </Inline>
+  );
+}
+
+/*** Renders one breadcrumb item and its optional following separator. */
+function BreadcrumbItemView({
+  compact,
+  current,
+  disabled,
+  interactionPolicy,
+  item,
+  onItemPress,
+  separator,
+  testID,
+}: {
+  compact: boolean;
+  current: boolean;
+  disabled: boolean;
+  interactionPolicy: BreadcrumbsProps['interactionPolicy'];
+  item: BreadcrumbItem;
+  onItemPress: ((event: BreadcrumbPressEvent) => void) | undefined;
+  separator: string | undefined;
+  testID: string | undefined;
+}) {
+  const interactive = !current && !disabled && !item.disabled && onItemPress !== undefined;
+
+  return (
+    <>
+      {interactive ? (
+        <Button
+          color="neutral"
+          interactionPolicy={interactionPolicy}
+          leadingIcon={item.icon}
+          onPress={() => onItemPress({ id: item.id })}
+          size={compact ? 's' : 'm'}
+          testID={testID ? `${testID}-item-${item.id}` : undefined}
+          variant="ghost"
+        >
+          {item.label}
+        </Button>
+      ) : (
+        <BreadcrumbLabel compact={compact} item={item} />
+      )}
+      {separator === undefined ? null : renderSeparator(separator)}
+    </>
+  );
+}
+
+/*** Renders one non-interactive breadcrumb label. */
+function BreadcrumbLabel({ item, compact }: { item: BreadcrumbItem; compact: boolean }) {
+  const { theme } = useZoraTheme();
+
+  return (
+    <Inline align="center" gap="xs" wrap="nowrap">
+      {item.icon ? (
+        <Icon
+          {...item.icon}
+          color={theme.semantics.content.muted}
+          size={resolveIconSize(compact ? 's' : 'm')}
+        />
+      ) : null}
+      <Text emphasis="muted" variant={compact ? 'caption' : 'bodySmall'}>
+        {item.label}
+      </Text>
+    </Inline>
+  );
+}
+
+/*** Renders the configured separator with muted breadcrumb styling. */
+function renderSeparator(separator: string): React.ReactNode {
+  return (
+    <Text emphasis="muted" variant="bodySmall">
+      {separator}
+    </Text>
+  );
+}
+
+/*** Normalizes an optional maximum breadcrumb item count. */
+function normalizeMaxItems(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) return undefined;
+  return Math.max(0, Math.trunc(value));
+}
+
+/*** Collapses middle breadcrumb items into one ellipsis when required. */
+function createRenderItems(
+  items: readonly BreadcrumbItem[],
+  maxItems: number | undefined,
+): readonly BreadcrumbRenderItem[] {
+  if (maxItems === undefined || maxItems === 0 || items.length <= maxItems || maxItems < 3) {
+    return items.map((item) => ({ item, type: 'item' }));
+  }
+
+  const firstItem = items.at(0);
+  if (firstItem === undefined) return [];
+
+  const trailingCount = maxItems - 2;
+  const trailingItems = items.slice(items.length - trailingCount);
+  return [
+    { item: firstItem, type: 'item' },
+    { type: 'ellipsis' },
+    ...trailingItems.map((item) => ({ item, type: 'item' }) satisfies BreadcrumbRenderItem),
+  ];
+}