@ankhorage/zora 2.4.7 → 2.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ankhorage/zora",
   "type": "module",
-  "version": "2.4.7",
+  "version": "2.5.0",
   "description": "Opinionated React Native and React Native Web UI kit built on @ankhorage/surface.",
   "homepage": "https://github.com/ankhorage/zora#readme",
   "bugs": {
@@ -44,7 +44,7 @@
   },
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7",
-    "@ankhorage/contracts": "^1.7.0",
+    "@ankhorage/contracts": "^1.12.0",
     "@ankhorage/surface": "^2.0.2"
   },
   "files": [
@@ -63,6 +63,13 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./metadata": {
+      "react-native": "./src/metadata/index.ts",
+      "browser": "./src/metadata/index.ts",
+      "types": "./dist/metadata/index.d.ts",
+      "import": "./dist/metadata/index.js",
+      "default": "./dist/metadata/index.js"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -72,6 +79,7 @@
     "build": "rm -rf dist tsconfig.tsbuildinfo && bun x tsc -p tsconfig.json",
     "changeset": "changeset",
     "changeset:status": "changeset status --since=origin/main",
+    "docs": "paradox",
     "knip": "ankhorage-knip",
     "lint": "ankhorage-eslint . --max-warnings=0",
     "lint:fix": "ankhorage-eslint . --fix --max-warnings=0",
@@ -84,6 +92,7 @@
   },
   "devDependencies": {
     "@ankhorage/devtools": "^1.0.6",
+    "@ankhorage/paradox": "^0.1.7",
     "@changesets/cli": "^2.31.0",
     "@expo/vector-icons": "^15.1.1",
     "@react-native-picker/picker": "^2.11.4",

package/src/components/breadcrumbs/Breadcrumbs.tsx

@@ -0,0 +1,143 @@
+import React from 'react';
+
+import { Inline } from '../../foundation';
+import { resolveIconSize } from '../../internal/recipes';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { Button } from '../button';
+import { Icon } from '../icon';
+import { Text } from '../text';
+import type { BreadcrumbItem, BreadcrumbsProps } from './types';
+
+type BreadcrumbRenderItem =
+  | {
+      item: BreadcrumbItem;
+      type: 'item';
+    }
+  | {
+      type: 'ellipsis';
+    };
+
+function normalizeMaxItems(value: number | undefined): number | undefined {
+  if (value === undefined || !Number.isFinite(value)) {
+    return undefined;
+  }
+
+  return Math.max(0, Math.trunc(value));
+}
+
+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;
+  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),
+  ];
+}
+
+function renderSeparator(separator: React.ReactNode) {
+  return (
+    <Text emphasis="muted" variant="bodySmall">
+      {separator}
+    </Text>
+  );
+}
+
+function BreadcrumbLabel({ item, compact }: { item: BreadcrumbItem; compact: boolean }) {
+  const { theme } = useZoraTheme();
+
+  return (
+    <Inline align="center" gap="xs" wrap="nowrap">
+      {item.icon ? (
+        <Icon
+          color={theme.semantics.content.muted}
+          name={item.icon.name}
+          provider={item.icon.provider}
+          size={resolveIconSize(compact ? 's' : 'm')}
+        />
+      ) : null}
+      <Text emphasis="muted" variant={compact ? 'caption' : 'bodySmall'}>
+        {item.label}
+      </Text>
+    </Inline>
+  );
+}
+
+function BreadcrumbsInner({
+  themeId: _themeId,
+  mode: _mode,
+  items,
+  separator = '/',
+  maxItems,
+  compact = false,
+  disabled = false,
+  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 isLastRenderedItem = index === renderItems.length - 1;
+        const showSeparator = !isLastRenderedItem;
+
+        if (renderItem.type === 'ellipsis') {
+          return (
+            <React.Fragment key="ellipsis">
+              <Text emphasis="muted" variant={compact ? 'caption' : 'bodySmall'}>
+                …
+              </Text>
+              {showSeparator ? renderSeparator(separator) : null}
+            </React.Fragment>
+          );
+        }
+
+        const { item } = renderItem;
+        const current = item.id === currentItemId;
+        const interactive = !current && !disabled && !item.disabled && Boolean(item.onPress);
+
+        return (
+          <React.Fragment key={item.id}>
+            {interactive ? (
+              <Button
+                color="neutral"
+                leadingIcon={item.icon}
+                onPress={item.onPress}
+                size={compact ? 's' : 'm'}
+                testID={testID ? `${testID}-item-${item.id}` : undefined}
+                variant="ghost"
+              >
+                {item.label}
+              </Button>
+            ) : (
+              <BreadcrumbLabel item={item} compact={compact} />
+            )}
+            {showSeparator ? renderSeparator(separator) : null}
+          </React.Fragment>
+        );
+      })}
+    </Inline>
+  );
+}
+
+export const Breadcrumbs = withZoraThemeScope(BreadcrumbsInner);

package/src/components/breadcrumbs/index.ts

@@ -0,0 +1,2 @@
+export { Breadcrumbs } from './Breadcrumbs';
+export type { BreadcrumbItem, BreadcrumbsProps } from './types';

package/src/components/breadcrumbs/meta.ts

@@ -0,0 +1,10 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const breadcrumbsMeta = {
+  name: 'Breadcrumbs',
+  category: 'component',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: 'Code-facing route hierarchy component; not represented as a manifest node in v1.',
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/components/breadcrumbs/types.ts

@@ -0,0 +1,21 @@
+import type { ButtonIconSpec } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface BreadcrumbItem {
+  id: string;
+  label: React.ReactNode;
+  icon?: ButtonIconSpec;
+  onPress?: () => void;
+  disabled?: boolean;
+}
+
+export interface BreadcrumbsProps extends ZoraBaseProps {
+  items: readonly BreadcrumbItem[];
+  separator?: React.ReactNode;
+  maxItems?: number;
+  compact?: boolean;
+  disabled?: boolean;
+  testID?: string;
+}

package/src/index.ts

@@ -8,6 +8,8 @@ export type { AvatarGroupItem, AvatarGroupProps } from './components/avatar-grou
 export { AvatarGroup } from './components/avatar-group';
 export type { BadgeProps } from './components/badge';
 export { Badge } from './components/badge';
+export type { BreadcrumbItem, BreadcrumbsProps } from './components/breadcrumbs';
+export { Breadcrumbs } from './components/breadcrumbs';
 export type { ButtonProps } from './components/button';
 export { Button } from './components/button';
 export type {
@@ -192,6 +194,7 @@ export { SidebarLayout } from './layout/sidebar-layout';
 export type { TopbarLayoutProps } from './layout/topbar-layout';
 export { TopbarLayout } from './layout/topbar-layout';
 export type {
+  ZoraBindableComponentType,
   ZoraComponentBlueprint,
   ZoraComponentCategory,
   ZoraComponentEventMeta,
@@ -207,7 +210,7 @@ export type {
   ZoraComponentPropValue,
   ZoraComponentSlotMeta,
 } from './metadata';
-export { ZORA_COMPONENT_META } from './metadata';
+export { ZORA_BINDABLE_COMPONENT_META, ZORA_COMPONENT_META } from './metadata';
 export type {
   AuthFormBaseProps,
   AuthIdentifierKind,

package/src/metadata/bindableComponentMeta.test.ts

@@ -0,0 +1,18 @@
+import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
+import { describe, expect, it } from 'bun:test';
+
+import { ZORA_BINDABLE_COMPONENT_META } from './bindableComponentMeta';
+
+describe('ZORA bindable component metadata', () => {
+  it('matches the shared UI metadata registry shape', () => {
+    const registry: UiComponentMetaRegistry = ZORA_BINDABLE_COMPONENT_META;
+
+    expect(registry.Text?.bindings?.props?.text?.value.type).toBe('string');
+    expect(registry.Heading?.bindings?.props?.text?.value.type).toBe('string');
+    expect(registry.Button?.bindings?.props?.children?.value.type).toBe('string');
+    expect(registry.Input?.bindings?.props?.value?.value.type).toBe('string');
+    expect(registry.Select?.bindings?.props?.value?.value.type).toBe('string');
+    expect(registry.Image?.bindings?.props?.source?.value.type).toBe('imageAsset');
+    expect(registry.DataTable?.bindings?.props?.rows?.value.type).toBe('array');
+  });
+});