@ankhorage/zora 14.0.1 → 16.0.0

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/dialog/adapters/inbound/Dialog.tsx

@@ -0,0 +1,70 @@
+import { Modal as SurfaceModal } from '@ankhorage/surface';
+import React from 'react';
+import { StyleSheet } from 'react-native';
+
+import { resolveDialogWidth } from '../../../../internal/recipes';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { DialogProps } from '../../../../types/dialog';
+import { Box, Stack } from '../../../layout/public';
+import { Heading, Text } from '../../../typography/public';
+
+/*** Renders the product-level dialog composition on top of the Surface modal primitive. */
+export const Dialog = withZoraThemeScope(DialogInner);
+
+/*** Connects dialog chrome and slots to the generic modal overlay. */
+function DialogInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  title,
+  description,
+  footer,
+  width = 'default',
+  onDismiss,
+  interactionPolicy,
+  ...props
+}: DialogProps) {
+  const hasHeader = title !== undefined || description !== undefined;
+  const stableOnDismiss = useStableCallback(onDismiss);
+
+  return (
+    <SurfaceModal {...props} onDismiss={stableOnDismiss} interactionPolicy={interactionPolicy}>
+      <Box maxWidth={resolveDialogWidth(width)} style={styles.content}>
+        <Stack gap="m">
+          {hasHeader ? (
+            <Stack gap="xs">
+              {title !== undefined ? <Heading level={3}>{title}</Heading> : null}
+              {description !== undefined ? (
+                <Text emphasis="muted" variant="bodySmall">
+                  {description}
+                </Text>
+              ) : null}
+            </Stack>
+          ) : null}
+          {children ? <Box>{children}</Box> : null}
+          {footer ? <Box pt="xs">{footer}</Box> : null}
+        </Stack>
+      </Box>
+    </SurfaceModal>
+  );
+}
+
+/*** Keeps the dismiss callback identity stable while always invoking the latest handler. */
+function useStableCallback(callback: (() => void) | undefined): (() => void) | undefined {
+  const callbackRef = React.useRef(callback);
+
+  React.useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  return React.useCallback(() => {
+    callbackRef.current?.();
+  }, []);
+}
+
+const styles = StyleSheet.create({
+  content: {
+    alignSelf: 'center',
+    width: '100%',
+  },
+});

package/src/features/dialog/dialogMeta.ts

@@ -0,0 +1,60 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const dialogMeta = {
+  name: 'Dialog',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  description: 'Modal dialog composition with title, description, content, and optional footer.',
+  blueprint: {
+    label: 'Dialog',
+    defaultProps: { closeOnBackdrop: true, visible: false, width: 'default' },
+  },
+  bindings: {
+    props: {
+      visible: {
+        label: 'Visible',
+        description: 'Whether the dialog is currently visible.',
+        value: { type: 'boolean' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+    events: {
+      dismiss: {
+        label: 'Dismiss',
+        description: 'Runs when the dialog requests dismissal.',
+        payload: { eventType: 'dialog.dismiss', fields: [] },
+      },
+    },
+  },
+  events: {
+    dismiss: { label: 'Dismiss', eventType: 'dialog.dismiss', payloadFields: [] },
+  },
+  slots: {
+    children: { label: 'Content', allowedChildren: [...CONTAINER_ALLOWED_CHILDREN] },
+    footer: {
+      label: 'Footer',
+      allowedChildren: ['Button', 'ButtonGroup', 'Stack', 'Toolbar'],
+    },
+  },
+  props: {
+    visible: { type: 'boolean', category: 'State', label: 'Visible', default: false },
+    title: { type: 'string', category: 'Content', label: 'Title' },
+    description: { type: 'string', category: 'Content', label: 'Description' },
+    closeOnBackdrop: {
+      type: 'boolean',
+      category: 'Behavior',
+      label: 'Close on backdrop',
+      default: true,
+    },
+    width: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Width',
+      enum: ['narrow', 'default', 'wide'],
+      default: 'default',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/dialog/public.ts

@@ -0,0 +1,2 @@
+export type { DialogProps } from '../../types/dialog';
+export { Dialog } from './adapters/inbound/Dialog';

package/src/features/form/formFieldMeta.ts

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

package/src/{components/search-bar/SearchBar.tsx → features/form/search-input/adapters/inbound/SearchInput.tsx}

@@ -1,14 +1,16 @@
-import React from 'react';
+import { withZoraThemeScope } from '../../../../../theme/withZoraThemeScope';
+import type { SearchInputProps } from '../../../../../types/search-input';
+import { TextInput, type TextInputTrailingAction } from '../../../text-input/public';
 
-import { TextInput, type TextInputTrailingAction } from '../../features/form/text-input/public';
-import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
-import type { SearchBarProps } from './types';
+/*** Renders a search-focused text input with clear and submit behavior. */
+export const SearchInput = withZoraThemeScope(SearchInputInner);
 
-function SearchBarInner({
+/*** Connects search semantics to the shared ZORA TextInput control. */
+function SearchInputInner({
   themeId: _themeId,
   mode: _mode,
   testID,
-  value,
+  value = '',
   onValueChange,
   placeholder = 'Search',
   onSubmit,
@@ -18,9 +20,8 @@ function SearchBarInner({
   disabled,
   readOnly,
   interactionPolicy,
-}: SearchBarProps) {
+}: SearchInputProps) {
   const passive = interactionPolicy === 'passive';
-
   const trailingAction: TextInputTrailingAction | undefined =
     clearable && value.length > 0
       ? {
@@ -28,8 +29,7 @@ function SearchBarInner({
           label: 'Clear search',
           onPress: () => {
             if (passive) return;
-
-            onValueChange('');
+            onValueChange?.('');
             onClear?.();
           },
         }
@@ -52,8 +52,3 @@ function SearchBarInner({
     />
   );
 }
-
-/***
- * Search input with leading icon and optional trailing action.
- */
-export const SearchBar = withZoraThemeScope(SearchBarInner);

package/src/features/form/search-input/public.ts

@@ -0,0 +1,2 @@
+export type { SearchInputProps } from '../../../types/search-input';
+export { SearchInput } from './adapters/inbound/SearchInput';

package/src/features/form/search-input/searchInputMeta.ts

@@ -0,0 +1,68 @@
+import type { ZoraComponentMeta } from '../../../metadata/types';
+
+export const searchInputMeta = {
+  name: 'SearchInput',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  description: 'Search-focused text input with clear and submit events.',
+  blueprint: {
+    label: 'Search input',
+    defaultProps: { clearable: true, placeholder: 'Search', size: 'l', value: '' },
+  },
+  bindings: {
+    props: {
+      value: {
+        label: 'Value',
+        description: 'Current search query.',
+        value: { type: 'string' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+    events: {
+      valueChange: {
+        label: 'Value change',
+        description: 'Runs whenever the search query changes.',
+        payload: {
+          eventType: 'searchInput.valueChange',
+          fields: [{ path: 'value', type: 'string', label: 'Value' }],
+        },
+      },
+      submit: {
+        label: 'Submit',
+        description: 'Runs when the user submits the search query.',
+        payload: {
+          eventType: 'searchInput.submit',
+          fields: [{ path: 'value', type: 'string', label: 'Value' }],
+        },
+      },
+      clear: {
+        label: 'Clear',
+        description: 'Runs when the search query is cleared.',
+        payload: { eventType: 'searchInput.clear', fields: [] },
+      },
+    },
+  },
+  events: {
+    valueChange: {
+      label: 'Value change',
+      eventType: 'searchInput.valueChange',
+      payloadFields: [{ path: 'value', type: 'string', label: 'Value' }],
+    },
+    submit: {
+      label: 'Submit',
+      eventType: 'searchInput.submit',
+      payloadFields: [{ path: 'value', type: 'string', label: 'Value' }],
+    },
+    clear: { label: 'Clear', eventType: 'searchInput.clear', payloadFields: [] },
+  },
+  props: {
+    value: { type: 'string', category: 'Content', label: 'Value', default: '' },
+    placeholder: { type: 'string', category: 'Content', label: 'Placeholder', default: 'Search' },
+    clearable: { type: 'boolean', category: 'Behavior', label: 'Clearable', default: true },
+    size: { type: 'enum', category: 'Style', label: 'Size', enum: ['s', 'm', 'l'], default: 'l' },
+    disabled: { type: 'boolean', category: 'State', label: 'Disabled' },
+    readOnly: { type: 'boolean', category: 'State', label: 'Read only' },
+  },
+} as const satisfies ZoraComponentMeta;

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