@ankhorage/zora 14.0.1 → 16.0.0

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';

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

@@ -0,0 +1,154 @@
+import type { ZoraComponentMeta } from '../../../metadata';
+
+export const selectMeta = {
+  name: 'Select',
+  category: 'component',
+  description:
+    'Single-value form selection with Popover presentation on web and BottomSheet presentation on native.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Select',
+    defaultProps: {
+      label: 'Option',
+      placeholder: 'Select',
+      defaultValue: 'option-b',
+      options: [
+        { value: 'option-a', label: 'First option' },
+        { value: 'option-b', label: 'Second option' },
+        { value: 'option-c', label: 'Third option' },
+      ],
+      disabled: false,
+      readOnly: false,
+      invalid: false,
+    },
+  },
+  bindings: {
+    props: {
+      value: {
+        label: 'Value',
+        description: 'Currently selected option value.',
+        value: { type: 'string' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+      disabled: {
+        label: 'Disabled',
+        description: 'Whether the select is disabled.',
+        value: { type: 'boolean' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+    events: {
+      valueChange: {
+        label: 'Value change',
+        description: 'Runs when the selected option value changes.',
+        payload: {
+          eventType: 'select.valueChange',
+          fields: [{ path: 'value', type: 'string', label: 'Value' }],
+        },
+      },
+    },
+  },
+  events: {
+    valueChange: {
+      label: 'Value change',
+      eventType: 'select.valueChange',
+      description: 'Emitted when the selected option value changes.',
+      payloadFields: [{ path: 'value', type: 'string', label: 'Value' }],
+    },
+  },
+  props: {
+    defaultValue: {
+      type: 'string',
+      category: 'State',
+      label: 'Initial value',
+      authoring: { authority: 'instance' },
+    },
+    value: {
+      type: 'string',
+      category: 'State',
+      label: 'Value',
+      authoring: { authority: 'instance' },
+    },
+    options: {
+      type: 'array',
+      category: 'Content',
+      label: 'Options',
+      itemSchema: [
+        {
+          key: 'value',
+          schema: { type: 'string', category: 'Content', label: 'Value' },
+        },
+        {
+          key: 'label',
+          schema: { type: 'string', category: 'Content', label: 'Label' },
+        },
+        {
+          key: 'disabled',
+          schema: {
+            type: 'boolean',
+            category: 'State',
+            label: 'Disabled',
+            default: false,
+          },
+        },
+      ],
+      authoring: { authority: 'instance' },
+    },
+    label: {
+      type: 'string',
+      category: 'Content',
+      label: 'Label',
+      authoring: { authority: 'instance' },
+    },
+    helperText: {
+      type: 'string',
+      category: 'Content',
+      label: 'Helper text',
+      authoring: { authority: 'instance' },
+    },
+    errorText: {
+      type: 'string',
+      category: 'Content',
+      label: 'Error text',
+      authoring: { authority: 'instance' },
+    },
+    placeholder: {
+      type: 'string',
+      category: 'Content',
+      label: 'Placeholder',
+      default: 'Select',
+      authoring: { authority: 'instance' },
+    },
+    required: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Required',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    disabled: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Disabled',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    readOnly: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Read only',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+    invalid: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Invalid',
+      default: false,
+      authoring: { authority: 'instance' },
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/pagination/adapters/inbound/Pagination.tsx

@@ -0,0 +1,116 @@
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { PaginationProps } from '../../../../types/pagination';
+import { Button } from '../../../button/public';
+import { Stack } from '../../../layout/public';
+import { Text } from '../../../typography/public';
+import { resolvePaginationPage } from '../../utils/resolvePaginationPage';
+import { resolvePaginationState } from '../../utils/resolvePaginationState';
+
+/*** Renders controls for navigating between pages of a finite result set. */
+export const Pagination = withZoraThemeScope(PaginationInner);
+
+/*** Connects normalized pagination state to visible page navigation controls. */
+function PaginationInner({
+  themeId: _themeId,
+  mode: _mode,
+  page,
+  pageCount,
+  onPageChange,
+  disabled = false,
+  siblingCount = 1,
+  boundaryCount = 1,
+  showFirstLast = false,
+  previousLabel = 'Previous',
+  nextLabel = 'Next',
+  firstLabel = 'First',
+  lastLabel = 'Last',
+  compact = false,
+  testID,
+  interactionPolicy,
+}: PaginationProps) {
+  const passive = interactionPolicy === 'passive';
+  const state = resolvePaginationState({ boundaryCount, compact, page, pageCount, siblingCount });
+  const canGoPrevious = state.currentPage > 1;
+  const canGoNext = state.currentPage < state.pageCount;
+  const navigationDisabled = disabled || state.pageCount <= 1;
+
+  const changePage = React.useCallback(
+    (nextPage: number) => {
+      const clampedPage = resolvePaginationPage(nextPage, state.pageCount);
+      if (passive || disabled || clampedPage === state.currentPage) return;
+      onPageChange?.(clampedPage);
+    },
+    [disabled, onPageChange, passive, state.currentPage, state.pageCount],
+  );
+
+  return (
+    <Stack align="center" direction="row" gap="xs" testID={testID}>
+      {showFirstLast ? (
+        <Button
+          disabled={navigationDisabled || state.currentPage === 1}
+          interactionPolicy={interactionPolicy}
+          onPress={() => changePage(1)}
+          size="s"
+          testID={testID ? `${testID}-first` : undefined}
+          variant="ghost"
+        >
+          {firstLabel}
+        </Button>
+      ) : null}
+      <Button
+        disabled={navigationDisabled || !canGoPrevious}
+        interactionPolicy={interactionPolicy}
+        onPress={() => changePage(state.currentPage - 1)}
+        size="s"
+        testID={testID ? `${testID}-previous` : undefined}
+        variant="ghost"
+      >
+        {previousLabel}
+      </Button>
+      {state.items.map((item, index) =>
+        item === 'ellipsis' ? (
+          <Text key={`ellipsis-${index}`} emphasis="muted" variant="bodySmall">
+            …
+          </Text>
+        ) : (
+          <Button
+            color={item === state.currentPage ? 'primary' : 'neutral'}
+            disabled={disabled}
+            interactionPolicy={interactionPolicy}
+            key={item}
+            onPress={() => changePage(item)}
+            size="s"
+            testID={testID ? `${testID}-page-${item}` : undefined}
+            variant={item === state.currentPage ? 'solid' : 'ghost'}
+          >
+            {item}
+          </Button>
+        ),
+      )}
+      <Button
+        disabled={navigationDisabled || !canGoNext}
+        interactionPolicy={interactionPolicy}
+        onPress={() => changePage(state.currentPage + 1)}
+        size="s"
+        testID={testID ? `${testID}-next` : undefined}
+        variant="ghost"
+      >
+        {nextLabel}
+      </Button>
+      {showFirstLast ? (
+        <Button
+          disabled={navigationDisabled || state.currentPage === state.pageCount}
+          interactionPolicy={interactionPolicy}
+          onPress={() => changePage(state.pageCount)}
+          size="s"
+          testID={testID ? `${testID}-last` : undefined}
+          variant="ghost"
+        >
+          {lastLabel}
+        </Button>
+      ) : null}
+    </Stack>
+  );
+}

package/src/features/pagination/paginationMeta.ts

@@ -0,0 +1,54 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const paginationMeta = {
+  name: 'Pagination',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  description: 'Navigates between pages of a finite result set without changing app routes.',
+  blueprint: {
+    label: 'Pagination',
+    defaultProps: { boundaryCount: 1, compact: false, page: 1, pageCount: 10, siblingCount: 1 },
+  },
+  bindings: {
+    props: {
+      page: {
+        label: 'Page',
+        description: 'Current one-based page.',
+        value: { type: 'number' },
+        acceptsFallback: true,
+        acceptsTransforms: true,
+      },
+    },
+    events: {
+      pageChange: {
+        label: 'Page change',
+        description: 'Runs when a new page is requested.',
+        payload: {
+          eventType: 'pagination.pageChange',
+          fields: [{ path: 'page', type: 'number', label: 'Page' }],
+        },
+      },
+    },
+  },
+  events: {
+    pageChange: {
+      label: 'Page change',
+      eventType: 'pagination.pageChange',
+      payloadFields: [{ path: 'page', type: 'number', label: 'Page' }],
+    },
+  },
+  props: {
+    page: { type: 'number', category: 'State', label: 'Page', default: 1 },
+    pageCount: { type: 'number', category: 'Data', label: 'Page count', default: 10 },
+    siblingCount: { type: 'number', category: 'Layout', label: 'Sibling count', default: 1 },
+    boundaryCount: { type: 'number', category: 'Layout', label: 'Boundary count', default: 1 },
+    showFirstLast: { type: 'boolean', category: 'Behavior', label: 'Show first/last' },
+    compact: { type: 'boolean', category: 'Layout', label: 'Compact', default: false },
+    disabled: { type: 'boolean', category: 'State', label: 'Disabled' },
+    previousLabel: { type: 'string', category: 'Content', label: 'Previous label' },
+    nextLabel: { type: 'string', category: 'Content', label: 'Next label' },
+    firstLabel: { type: 'string', category: 'Content', label: 'First label' },
+    lastLabel: { type: 'string', category: 'Content', label: 'Last label' },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/pagination/public.ts

@@ -0,0 +1,2 @@
+export type { PaginationProps } from '../../types/pagination';
+export { Pagination } from './adapters/inbound/Pagination';

package/src/features/pagination/utils/resolvePaginationPage.ts

@@ -0,0 +1,6 @@
+/*** Clamps a requested pagination page to the valid one-based page range. */
+export function resolvePaginationPage(value: number, pageCount: number): number {
+  if (!Number.isFinite(value)) return 1;
+
+  return Math.min(Math.max(Math.trunc(value), 1), Math.max(pageCount, 1));
+}

package/src/features/pagination/utils/resolvePaginationState.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolvePaginationState } from './resolvePaginationState';
+
+describe('resolvePaginationState', () => {
+  it('inserts ellipses between boundaries and siblings', () => {
+    expect(
+      resolvePaginationState({
+        boundaryCount: 1,
+        compact: false,
+        page: 5,
+        pageCount: 10,
+        siblingCount: 1,
+      }).items,
+    ).toEqual([1, 'ellipsis', 4, 5, 6, 'ellipsis', 10]);
+  });
+
+  it('returns only the active page in compact mode', () => {
+    expect(
+      resolvePaginationState({
+        boundaryCount: 1,
+        compact: true,
+        page: 3,
+        pageCount: 8,
+        siblingCount: 1,
+      }).items,
+    ).toEqual([3]);
+  });
+});

package/src/features/pagination/utils/resolvePaginationState.ts

@@ -0,0 +1,70 @@
+import { resolvePaginationPage } from './resolvePaginationPage';
+
+/*** Normalizes pagination input and resolves visible page and ellipsis items. */
+export function resolvePaginationState({
+  page,
+  pageCount,
+  siblingCount,
+  boundaryCount,
+  compact,
+}: PaginationStateInput): PaginationState {
+  const normalizedPageCount = Math.max(0, Math.trunc(Number.isFinite(pageCount) ? pageCount : 0));
+  const currentPage = resolvePaginationPage(page, normalizedPageCount);
+  const safeSiblingCount = normalizeCount(siblingCount, 1);
+  const safeBoundaryCount = normalizeCount(boundaryCount, 1);
+
+  if (normalizedPageCount <= 0) {
+    return { currentPage, items: [], pageCount: normalizedPageCount };
+  }
+
+  if (compact) {
+    return { currentPage, items: [currentPage], pageCount: normalizedPageCount };
+  }
+
+  const boundaries = createRange(1, Math.min(safeBoundaryCount, normalizedPageCount));
+  const trailingBoundaries = createRange(
+    Math.max(normalizedPageCount - safeBoundaryCount + 1, 1),
+    normalizedPageCount,
+  );
+  const siblings = createRange(
+    Math.max(currentPage - safeSiblingCount, 1),
+    Math.min(currentPage + safeSiblingCount, normalizedPageCount),
+  );
+  const pages = [...new Set([...boundaries, ...siblings, ...trailingBoundaries])].sort(
+    (left, right) => left - right,
+  );
+  const items = pages.flatMap<PaginationItem>((nextPage, index) => {
+    const previousPage = index > 0 ? pages.at(index - 1) : undefined;
+    return previousPage !== undefined && nextPage - previousPage > 1
+      ? ['ellipsis', nextPage]
+      : [nextPage];
+  });
+
+  return { currentPage, items, pageCount: normalizedPageCount };
+}
+
+type PaginationItem = number | 'ellipsis';
+
+interface PaginationStateInput {
+  page: number;
+  pageCount: number;
+  siblingCount: number | undefined;
+  boundaryCount: number | undefined;
+  compact: boolean;
+}
+
+interface PaginationState {
+  currentPage: number;
+  pageCount: number;
+  items: readonly PaginationItem[];
+}
+
+/*** Creates an inclusive numeric range for pagination boundaries and siblings. */
+function createRange(start: number, end: number): number[] {
+  return end < start ? [] : Array.from({ length: end - start + 1 }, (_, index) => start + index);
+}
+
+/*** Normalizes optional pagination counts to finite non-negative integers. */
+function normalizeCount(value: number | undefined, fallback: number): number {
+  return value === undefined || !Number.isFinite(value) ? fallback : Math.max(0, Math.trunc(value));
+}

package/src/features/popover-menu/adapters/inbound/PopoverMenu.tsx

@@ -0,0 +1,60 @@
+import {
+  PopoverMenu as SurfacePopoverMenu,
+  type PopoverMenuAction as SurfacePopoverMenuAction,
+} from '@ankhorage/surface';
+import React from 'react';
+
+import { resolveIconSize } from '../../../../internal/recipes';
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { PopoverMenuAction, PopoverMenuProps } from '../../../../types/popover-menu';
+import { Icon } from '../../../icon/public';
+import { Box } from '../../../layout/public';
+
+/*** Presents a ZORA-styled action list through the Surface PopoverMenu capability. */
+export const PopoverMenu = withZoraThemeScope(PopoverMenuInner);
+
+/*** Maps ZORA action presentation into the Surface action-menu boundary. */
+function PopoverMenuInner({
+  themeId: _themeId,
+  mode: _mode,
+  actions,
+  onDismiss,
+  ...props
+}: PopoverMenuProps) {
+  const { theme } = useZoraTheme();
+  const iconColor = theme.semantics.content.muted;
+  const surfaceActions = React.useMemo(
+    () => actions.map((action) => toSurfaceAction(action, iconColor)),
+    [actions, iconColor],
+  );
+
+  return <SurfacePopoverMenu {...props} actions={surfaceActions} dismiss={onDismiss} />;
+}
+
+/*** Maps one ZORA PopoverMenu action to the Surface action contract. */
+function toSurfaceAction(action: PopoverMenuAction, iconColor: string): SurfacePopoverMenuAction {
+  return {
+    activate: action.onPress,
+    description: action.description,
+    disabled: action.disabled,
+    id: action.id,
+    intent: action.intent,
+    leading: renderActionLeading(action, iconColor),
+    selected: action.selected,
+    title: action.title,
+    trailing: renderActionTrailing(action),
+  };
+}
+
+/*** Resolves explicit leading content or the configured action icon. */
+function renderActionLeading(action: PopoverMenuAction, iconColor: string): React.ReactNode {
+  if (action.leading !== undefined) return action.leading;
+  if (action.icon === undefined) return undefined;
+  return <Icon {...action.icon} color={iconColor} size={resolveIconSize('s')} />;
+}
+
+/*** Wraps optional trailing action content in the ZORA layout boundary. */
+function renderActionTrailing(action: PopoverMenuAction): React.ReactNode {
+  return action.trailing === undefined ? undefined : <Box>{action.trailing}</Box>;
+}

package/src/{components/rating/meta.ts → features/popover-menu/popoverMenuMeta.ts}

@@ -1,10 +1,10 @@
 import type { ZoraComponentMeta } from '../../metadata';
 
-export const ratingMeta = {
-  name: 'Rating',
+export const popoverMenuMeta = {
+  name: 'PopoverMenu',
   category: 'component',
   directManifestNode: false,
   allowedChildren: [],
-  note: 'Feedback component; not represented as a manifest node in v1.',
+  note: 'Code-facing anchored action menu; the trigger is a render prop and is not serialized as a direct manifest node.',
   props: {},
 } as const satisfies ZoraComponentMeta;

package/src/features/popover-menu/public.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from 'bun:test';
+
+test('PopoverMenu composes the released Surface PopoverMenu capability', async () => {
+  const source = await Bun.file(
+    'src/features/popover-menu/adapters/inbound/PopoverMenu.tsx',
+  ).text();
+
+  expect(source).toContain('PopoverMenu as SurfacePopoverMenu');
+  expect(source).toContain('<SurfacePopoverMenu');
+  expect(source).not.toContain('DropdownMenu');
+});

package/src/features/popover-menu/public.ts

@@ -0,0 +1,6 @@
+export type {
+  PopoverMenuAction,
+  PopoverMenuActionIntent,
+  PopoverMenuProps,
+} from '../../types/popover-menu';
+export { PopoverMenu } from './adapters/inbound/PopoverMenu';