@ankhorage/zora 14.0.1 → 15.0.0

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

package/src/features/breadcrumbs/breadcrumbsMeta.ts

@@ -0,0 +1,95 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+export const breadcrumbsMeta = {
+  name: 'Breadcrumbs',
+  category: 'component',
+  description: 'Hierarchical route context where the final item represents the current location.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Breadcrumbs',
+    defaultProps: {
+      items: [
+        { id: 'settings', label: 'Settings' },
+        { id: 'general', label: 'General' },
+      ],
+      separator: '/',
+      compact: false,
+      disabled: false,
+    },
+  },
+  bindings: {
+    events: {
+      itemPress: {
+        label: 'Item press',
+        description: 'Runs when a non-current breadcrumb item is pressed.',
+        payload: {
+          eventType: 'breadcrumbs.itemPress',
+          fields: [{ path: 'id', type: 'string', label: 'Item id' }],
+        },
+      },
+    },
+  },
+  events: {
+    itemPress: {
+      label: 'Item press',
+      eventType: 'breadcrumbs.itemPress',
+      description: 'Emitted when a non-current breadcrumb item is pressed.',
+      payloadFields: [{ path: 'id', type: 'string', label: 'Item id' }],
+    },
+  },
+  props: {
+    items: {
+      type: 'array',
+      category: 'Content',
+      label: 'Items',
+      itemSchema: [
+        {
+          key: 'id',
+          schema: { type: 'string', category: 'Content', label: 'Id' },
+        },
+        {
+          key: 'label',
+          schema: { type: 'string', category: 'Content', label: 'Label' },
+        },
+        {
+          key: 'disabled',
+          schema: {
+            type: 'boolean',
+            category: 'State',
+            label: 'Disabled',
+            default: false,
+          },
+        },
+      ],
+      authoring: { authority: 'instance' },
+    },
+    separator: {
+      type: 'string',
+      category: 'Content',
+      label: 'Separator',
+      default: '/',
+      authoring: { authority: 'instance' },
+    },
+    maxItems: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Maximum items',
+      authoring: { authority: 'instance' },
+    },
+    compact: {
+      type: 'boolean',
+      category: 'Layout',
+      label: 'Compact',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/breadcrumbs/public.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test';
+
+import { breadcrumbsMeta } from './breadcrumbsMeta';
+
+test('Breadcrumbs is a direct manifest node with serializable item press payload', () => {
+  expect(breadcrumbsMeta.directManifestNode).toBe(true);
+  expect(breadcrumbsMeta.events.itemPress.eventType).toBe('breadcrumbs.itemPress');
+  expect(breadcrumbsMeta.events.itemPress.payloadFields).toEqual([
+    { path: 'id', type: 'string', label: 'Item id' },
+  ]);
+});
+
+test('Breadcrumbs keeps current-location derivation and callbacks outside item data', async () => {
+  const [source, types] = await Promise.all([
+    Bun.file('src/features/breadcrumbs/adapters/inbound/Breadcrumbs.tsx').text(),
+    Bun.file('src/types/breadcrumbs.ts').text(),
+  ]);
+
+  expect(source).toContain('const currentItemId = items.at(-1)?.id;');
+  expect(source).toContain('onItemPress({ id: item.id })');
+  expect(types).not.toContain('onPress?:');
+});

package/src/features/breadcrumbs/public.ts

@@ -0,0 +1,6 @@
+export type {
+  BreadcrumbItem,
+  BreadcrumbPressEvent,
+  BreadcrumbsProps,
+} from '../../types/breadcrumbs';
+export { Breadcrumbs } from './adapters/inbound/Breadcrumbs';

package/src/features/data-table/adapters/inbound/DataTable.tsx

@@ -2,7 +2,6 @@ import type { InteractionPolicy } from '@ankhorage/surface';
 import React from 'react';
 import { ScrollView, type ViewStyle } from 'react-native';
 
-import { DropdownMenu, type MenuAction } from '../../../../components/menu';
 import { Show } from '../../../../foundation';
 import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type {
@@ -19,6 +18,7 @@ import { IconButton } from '../../../button/public';
 import { Card } from '../../../card/public';
 import { EmptyState } from '../../../empty-state/public';
 import { Box, Stack } from '../../../layout/public';
+import { PopoverMenu, type PopoverMenuAction } from '../../../popover-menu/public';
 import { SkeletonList } from '../../../skeleton/public';
 import { Text, type TextAlign } from '../../../typography/public';
 import { resolveDataTableRowKey } from '../../utils/resolveDataTableRowKey';
@@ -139,10 +139,11 @@ function resolveNextSortDirection(
   return current === 'asc' ? 'desc' : 'asc';
 }
 
+/*** Maps row-scoped DataTable actions into the shared PopoverMenu action contract. */
 function mapRowActions<TRow extends object>(
   row: TRow,
   actions: readonly DataTableRowAction<TRow>[],
-): readonly MenuAction[] {
+): readonly PopoverMenuAction[] {
   return actions.map((action) => ({
     description: action.description,
     disabled: action.disabled,
@@ -154,6 +155,7 @@ function mapRowActions<TRow extends object>(
   }));
 }
 
+/*** Renders the row action trigger and anchored PopoverMenu when actions exist. */
 function renderRowActions<TRow extends object>({
   row,
   rowIndex,
@@ -174,18 +176,20 @@ function renderRowActions<TRow extends object>({
   }
 
   return (
-    <DropdownMenu
+    <PopoverMenu
       actions={mapRowActions(row, actions)}
       interactionPolicy={interactionPolicy}
       testID={testID ? `${testID}-row-actions-${rowIndex}` : undefined}
-      trigger={
+      trigger={({ toggle }) => (
         <IconButton
           icon={{ name: 'ellipsis-horizontal' }}
+          interactionPolicy={interactionPolicy}
           label="Row actions"
+          onPress={toggle}
           size="s"
           variant="ghost"
         />
-      }
+      )}
     />
   );
 }

package/src/features/form/formFieldMeta.ts

@@ -3,7 +3,7 @@ export const formFieldMeta = {
   name: 'FormField',
   category: 'component',
   directManifestNode: true,
-  allowedChildren: ['Checkbox', 'CheckboxGroup', 'RadioGroup', 'TextInput'],
+  allowedChildren: ['Checkbox', 'CheckboxGroup', 'RadioGroup', 'Select', 'TextInput'],
   blueprint: { label: 'Form field', defaultProps: { label: 'Label' } },
   bindings: {
     props: {

package/src/features/form/select/adapters/inbound/Select.native.tsx

@@ -0,0 +1,78 @@
+import React from 'react';
+import { type ListRenderItemInfo, StyleSheet } from 'react-native';
+
+import { withZoraThemeScope } from '../../../../../theme/withZoraThemeScope';
+import type { SelectOption, SelectProps } from '../../../../../types/select';
+import { BottomSheetFlatList, useBottomSheet } from '../../../../bottom-sheet/public';
+import { SelectField } from '../../composition/SelectField';
+import { SelectOptionRow } from '../../composition/SelectOptionRow';
+import { SelectTrigger } from '../../composition/SelectTrigger';
+import { useSelectController } from '../../composition/useSelectController';
+
+const SELECT_SHEET_MAX_HEIGHT = 480;
+
+/*** Renders Select with BottomSheetFlatList presentation on native platforms. */
+export const Select = withZoraThemeScope(SelectInner);
+
+/*** Connects shared Select state and controls to the native BottomSheet host. */
+function SelectInner<TValue extends string = string>({
+  themeId: _themeId,
+  mode: _mode,
+  ...props
+}: SelectProps<TValue>) {
+  const { dismiss, present } = useBottomSheet();
+  const { select, selectedOption, value } = useSelectController(props);
+  const passive = props.interactionPolicy === 'passive';
+  const { disabled, interactionPolicy, options, readOnly, testID } = props;
+  const listData = React.useMemo(() => [...options], [options]);
+
+  const handleSelect = React.useCallback(
+    (nextValue: TValue) => {
+      select(nextValue);
+      dismiss();
+    },
+    [dismiss, select],
+  );
+
+  const renderOption = React.useCallback(
+    ({ item }: ListRenderItemInfo<SelectOption<TValue>>) => (
+      <SelectOptionRow
+        interactionPolicy={interactionPolicy}
+        onSelect={handleSelect}
+        option={item}
+        selected={value === item.value}
+        testID={testID}
+      />
+    ),
+    [handleSelect, interactionPolicy, testID, value],
+  );
+
+  const openSelect = React.useCallback(() => {
+    if (disabled || readOnly || passive) return;
+
+    present({
+      contentMode: 'direct',
+      maxDynamicContentSize: SELECT_SHEET_MAX_HEIGHT,
+      content: (
+        <BottomSheetFlatList
+          contentContainerStyle={styles.listContent}
+          data={listData}
+          keyExtractor={(item) => item.value}
+          renderItem={renderOption}
+        />
+      ),
+    });
+  }, [disabled, listData, passive, present, readOnly, renderOption]);
+
+  return (
+    <SelectField props={props}>
+      <SelectTrigger displayLabel={selectedOption?.label} onPress={openSelect} props={props} />
+    </SelectField>
+  );
+}
+
+const styles = StyleSheet.create({
+  listContent: {
+    padding: 16,
+  },
+});

package/src/features/form/select/adapters/inbound/Select.tsx

@@ -0,0 +1 @@
+export { Select } from './Select.web';

package/src/features/form/select/adapters/inbound/Select.web.tsx

@@ -0,0 +1,63 @@
+import { Popover } from '@ankhorage/surface';
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../../theme/withZoraThemeScope';
+import type { SelectProps } from '../../../../../types/select';
+import { Stack } from '../../../../layout/public';
+import { Surface } from '../../../../surface/public';
+import { SelectField } from '../../composition/SelectField';
+import { SelectOptionRow } from '../../composition/SelectOptionRow';
+import { SelectTrigger } from '../../composition/SelectTrigger';
+import { useSelectController } from '../../composition/useSelectController';
+
+/*** Renders Select with anchored Popover presentation on web. */
+export const Select = withZoraThemeScope(SelectInner);
+
+/*** Connects shared Select state and controls to the web Popover host. */
+function SelectInner<TValue extends string = string>({
+  themeId: _themeId,
+  mode: _mode,
+  ...props
+}: SelectProps<TValue>) {
+  const [open, setOpen] = React.useState(false);
+  const { select, selectedOption, value } = useSelectController(props);
+  const { interactionPolicy, options, testID } = props;
+
+  const selectAndClose = React.useCallback(
+    (nextValue: TValue) => {
+      select(nextValue);
+      setOpen(false);
+    },
+    [select],
+  );
+
+  return (
+    <SelectField props={props}>
+      <Popover
+        anchor={({ toggle }) => (
+          <SelectTrigger displayLabel={selectedOption?.label} onPress={toggle} props={props} />
+        )}
+        interactionPolicy={props.interactionPolicy}
+        onOpenChange={setOpen}
+        open={open}
+        placement="bottom-start"
+        testID={testID ? `${testID}-popover` : undefined}
+      >
+        <Surface variant="raised">
+          <Stack gap="xs" p="xs">
+            {options.map((option) => (
+              <SelectOptionRow
+                interactionPolicy={interactionPolicy}
+                key={option.value}
+                onSelect={selectAndClose}
+                option={option}
+                selected={value === option.value}
+                testID={testID}
+              />
+            ))}
+          </Stack>
+        </Surface>
+      </Popover>
+    </SelectField>
+  );
+}

package/src/features/form/select/composition/SelectField.tsx

@@ -0,0 +1,27 @@
+import { Field } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { SelectProps } from '../../../../types/select';
+
+/*** Wraps Select presentation in the canonical Surface form-field semantics. */
+export function SelectField<TValue extends string>({ children, props }: SelectFieldProps<TValue>) {
+  return (
+    <Field
+      disabled={props.disabled}
+      errorText={props.errorText}
+      helperText={props.helperText}
+      invalid={props.invalid}
+      label={props.label}
+      readOnly={props.readOnly}
+      required={props.required}
+      testID={props.testID ? `${props.testID}-field` : undefined}
+    >
+      {children}
+    </Field>
+  );
+}
+
+interface SelectFieldProps<TValue extends string> {
+  children: React.ReactNode;
+  props: SelectProps<TValue>;
+}

package/src/features/form/select/composition/SelectOptionRow.tsx

@@ -0,0 +1,36 @@
+import type { SelectOption, SelectProps } from '../../../../types/select';
+import { Button } from '../../../button/public';
+
+const SELECTED_ICON = { name: 'checkmark' } as const;
+
+/*** Renders one Select option with shared web/native selection semantics. */
+export function SelectOptionRow<TValue extends string>({
+  interactionPolicy,
+  onSelect,
+  option,
+  selected,
+  testID,
+}: SelectOptionRowProps<TValue>) {
+  return (
+    <Button
+      color={selected ? 'primary' : 'neutral'}
+      disabled={option.disabled}
+      fullWidth
+      interactionPolicy={interactionPolicy}
+      onPress={() => onSelect(option.value)}
+      testID={testID ? `${testID}-option-${option.value}` : undefined}
+      trailingIcon={selected ? SELECTED_ICON : undefined}
+      variant={selected ? 'soft' : 'ghost'}
+    >
+      {option.label}
+    </Button>
+  );
+}
+
+interface SelectOptionRowProps<TValue extends string> {
+  interactionPolicy: SelectProps<TValue>['interactionPolicy'];
+  onSelect: (value: TValue) => void;
+  option: SelectOption<TValue>;
+  selected: boolean;
+  testID: string | undefined;
+}

package/src/features/form/select/composition/SelectTrigger.tsx

@@ -0,0 +1,32 @@
+import type { SelectProps } from '../../../../types/select';
+import { Button } from '../../../button/public';
+
+const SELECT_CHEVRON_ICON = { name: 'chevron-down' } as const;
+
+/*** Renders the shared Select trigger with the resolved option label or placeholder. */
+export function SelectTrigger<TValue extends string>({
+  displayLabel,
+  onPress,
+  props,
+}: SelectTriggerProps<TValue>) {
+  return (
+    <Button
+      color={props.invalid ? 'danger' : 'neutral'}
+      disabled={props.disabled}
+      fullWidth
+      interactionPolicy={props.interactionPolicy}
+      onPress={props.readOnly ? undefined : onPress}
+      testID={props.testID ? `${props.testID}-trigger` : undefined}
+      trailingIcon={SELECT_CHEVRON_ICON}
+      variant="outline"
+    >
+      {displayLabel ?? props.placeholder ?? 'Select'}
+    </Button>
+  );
+}
+
+interface SelectTriggerProps<TValue extends string> {
+  displayLabel: string | undefined;
+  onPress: () => void;
+  props: SelectProps<TValue>;
+}

package/src/features/form/select/composition/useSelectController.ts

@@ -0,0 +1,21 @@
+import React from 'react';
+
+import type { SelectProps } from '../../../../types/select';
+
+/*** Resolves controlled or uncontrolled Select value state and the selected option. */
+export function useSelectController<TValue extends string>(props: SelectProps<TValue>) {
+  const { defaultValue, onValueChange, options, value: controlledValue } = props;
+  const [localValue, setLocalValue] = React.useState<TValue | undefined>(defaultValue);
+  const value = controlledValue ?? localValue;
+  const selectedOption = options.find((option) => option.value === value);
+
+  const select = React.useCallback(
+    (nextValue: TValue) => {
+      if (controlledValue === undefined) setLocalValue(nextValue);
+      onValueChange?.(nextValue);
+    },
+    [controlledValue, onValueChange],
+  );
+
+  return { select, selectedOption, value } as const;
+}

package/src/features/form/select/public.test.ts

@@ -0,0 +1,25 @@
+import { expect, test } from 'bun:test';
+
+import { selectMeta } from './selectMeta';
+
+test('Select is a direct manifest node with valueChange payload', () => {
+  expect(selectMeta.directManifestNode).toBe(true);
+  expect(selectMeta.events.valueChange.eventType).toBe('select.valueChange');
+  expect(selectMeta.events.valueChange.payloadFields).toEqual([
+    { path: 'value', type: 'string', label: 'Value' },
+  ]);
+});
+
+test('Select uses web Popover and native BottomSheetFlatList presentation', async () => {
+  const [neutral, web, native] = await Promise.all([
+    Bun.file('src/features/form/select/adapters/inbound/Select.tsx').text(),
+    Bun.file('src/features/form/select/adapters/inbound/Select.web.tsx').text(),
+    Bun.file('src/features/form/select/adapters/inbound/Select.native.tsx').text(),
+  ]);
+
+  expect(neutral).toContain("export { Select } from './Select.web';");
+  expect(web).toContain("import { Popover } from '@ankhorage/surface';");
+  expect(native).toContain('<BottomSheetFlatList');
+  expect(native).toContain("contentMode: 'direct'");
+  expect(`${neutral}\n${web}\n${native}`).not.toContain('@react-native-picker/picker');
+});

package/src/features/form/select/public.ts

@@ -0,0 +1,2 @@
+export type { SelectOption, SelectProps } from '../../../types/select';
+export { Select } from './adapters/inbound/Select';