@ankhorage/zora 1.1.0 → 1.3.0

package/src/components/app-bar/types.ts

@@ -0,0 +1,36 @@
+import type { ButtonIconSpec } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export type AppBarMode =
+  | {
+      type: 'default';
+    }
+  | {
+      type: 'selection';
+      label: string;
+      count?: number;
+      onCancel: () => void;
+      cancelLabel?: string;
+      cancelIcon?: ButtonIconSpec;
+    };
+
+export interface AppBarOverflowAction {
+  onPress: () => void;
+  label?: string;
+  icon?: ButtonIconSpec;
+  disabled?: boolean;
+}
+
+export interface AppBarProps extends ZoraBaseProps {
+  title?: React.ReactNode;
+  subtitle?: React.ReactNode;
+  leading?: React.ReactNode;
+  actions?: React.ReactNode;
+  overflow?: AppBarOverflowAction;
+  appMode?: AppBarMode;
+  children?: React.ReactNode;
+  safeAreaTop?: boolean;
+  divider?: boolean;
+}

package/src/components/input/types.ts

@@ -19,7 +19,7 @@ type InputTrailingProps =
       trailingAction?: InputTrailingAction;
     };
 
-export interface InputBaseProps
+interface InputBaseProps
   extends
     ZoraBaseProps,
     Omit<

package/src/components/toolbar/types.ts

@@ -1,10 +1,10 @@
 import type { ButtonIconSpec } from '@ankhorage/surface';
 import type React from 'react';
 
-export type ToolbarPosition = 'top' | 'bottom' | 'inline';
-
 import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
 
+export type ToolbarPosition = 'top' | 'bottom' | 'inline';
+
 export interface ToolbarProps extends ZoraBaseProps {
   children?: React.ReactNode;
   position?: ToolbarPosition;

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { AppBarMode, AppBarOverflowAction, AppBarProps } from './components/app-bar';
+export { AppBar } from './components/app-bar';
 export type { AvatarProps, AvatarShape, AvatarSize } from './components/avatar';
 export { Avatar, resolveAvatarInitials } from './components/avatar';
 export type { AvatarGroupItem, AvatarGroupProps } from './components/avatar-group';
@@ -86,13 +88,13 @@ export type { SearchBarProps } from './components/search-bar';
 export { SearchBar } from './components/search-bar';
 export type { SelectOption, SelectProps } from './components/select';
 export { Select } from './components/select';
-export type { TabItem, TabsProps } from './components/tabs';
+export type { TabItem, TabsProps, TabsVariant } from './components/tabs';
 export { Tabs } from './components/tabs';
 export type { TextAlign, TextProps, TextTone, TextVariant, TextWeight } from './components/text';
 export { Text } from './components/text';
 export type { TextareaProps } from './components/textarea';
 export { Textarea } from './components/textarea';
-export type { ToolbarActionProps, ToolbarProps } from './components/toolbar';
+export type { ToolbarActionProps, ToolbarPosition, ToolbarProps } from './components/toolbar';
 export { Toolbar, ToolbarAction } from './components/toolbar';
 export type {
   BoxProps,
@@ -189,10 +191,24 @@ export type { NoticeProps } from './patterns/notice';
 export { Notice } from './patterns/notice';
 export type { PanelProps } from './patterns/panel';
 export { Panel } from './patterns/panel';
-export type { ResponsivePanelProps } from './patterns/responsive-panel';
+export type {
+  ResponsivePanelDesktopMode,
+  ResponsivePanelMobileMode,
+  ResponsivePanelProps,
+  ResponsivePanelSide,
+} from './patterns/responsive-panel';
 export { ResponsivePanel } from './patterns/responsive-panel';
 export type { SectionHeaderProps } from './patterns/section-header';
 export { SectionHeader } from './patterns/section-header';
+export type {
+  SelectableItemProps,
+  SelectableItemState,
+  SelectionMode,
+  SelectionProviderProps,
+  SelectionTrigger,
+  UseSelectionResult,
+} from './patterns/selection';
+export { SelectableItem, SelectionProvider, useSelection } from './patterns/selection';
 export type { SettingsRowProps } from './patterns/settings-row';
 export { SettingsRow } from './patterns/settings-row';
 export type { SwitchFieldProps } from './patterns/switch-field';

package/src/internal/resolveZoraNavigationItems.ts

@@ -6,7 +6,7 @@ import type {
 } from '../components/navigation-item';
 import type { ZoraNavigationRouteMap } from '../components/navigation-list';
 
-export interface ZoraNavigationDescriptorOptions {
+interface ZoraNavigationDescriptorOptions {
   title?: string;
   tabBarLabel?: string | React.ReactNode;
   drawerLabel?: string | React.ReactNode;
@@ -25,13 +25,13 @@ export interface ZoraNavigationState {
   routes: readonly ZoraNavigationRouteState[];
 }
 
-export interface ZoraTabPressEvent {
+interface ZoraTabPressEvent {
   type: 'tabPress';
   target: string;
   canPreventDefault: true;
 }
 
-export interface ZoraTabPressEventResult {
+interface ZoraTabPressEventResult {
   defaultPrevented: boolean;
 }
 

package/src/patterns/list/types.ts

@@ -46,7 +46,7 @@ export interface ListChildrenProps extends ZoraBaseProps {
 
 export type ListProps = ListItemsProps | ListChildrenProps;
 
-export interface ListSectionItemsProps extends ZoraBaseProps {
+interface ListSectionItemsProps extends ZoraBaseProps {
   title?: React.ReactNode;
   description?: React.ReactNode;
   eyebrow?: React.ReactNode;
@@ -56,7 +56,7 @@ export interface ListSectionItemsProps extends ZoraBaseProps {
   compact?: boolean;
 }
 
-export interface ListSectionChildrenProps extends ZoraBaseProps {
+interface ListSectionChildrenProps extends ZoraBaseProps {
   title?: React.ReactNode;
   description?: React.ReactNode;
   eyebrow?: React.ReactNode;

package/src/patterns/responsive-panel/types.ts

@@ -1,11 +1,11 @@
 import type React from 'react';
 
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
 export type ResponsivePanelSide = 'left' | 'right';
 export type ResponsivePanelDesktopMode = 'inline' | 'floating';
 export type ResponsivePanelMobileMode = 'drawer' | 'modal';
 
-import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
-
 export interface ResponsivePanelProps extends ZoraBaseProps {
   title?: React.ReactNode;
   description?: React.ReactNode;

package/src/patterns/selection/SelectableItem.tsx

@@ -0,0 +1,93 @@
+import { ButtonBase } from '@ankhorage/surface';
+import React from 'react';
+import type { GestureResponderEvent } from 'react-native';
+
+import { useSelection } from './SelectionProvider';
+import type { SelectableItemProps, SelectableItemState, SelectionTrigger } from './types';
+
+function resolveTrigger(trigger: SelectionTrigger | undefined): SelectionTrigger {
+  return trigger ?? 'manual';
+}
+
+function isRenderProp(
+  children: SelectableItemProps['children'],
+): children is (state: SelectableItemState) => React.ReactNode {
+  return typeof children === 'function';
+}
+
+export function SelectableItem({ id, trigger, disabled = false, children }: SelectableItemProps) {
+  const selection = useSelection();
+  const resolvedTrigger = resolveTrigger(trigger);
+  const resolvedDisabled = selection.disabled || disabled;
+  const selected = selection.isSelected(id);
+
+  const select = React.useCallback(() => {
+    if (resolvedDisabled) return;
+    selection.select(id);
+  }, [id, resolvedDisabled, selection]);
+
+  const toggle = React.useCallback(() => {
+    if (resolvedDisabled) return;
+    selection.toggle(id);
+  }, [id, resolvedDisabled, selection]);
+
+  const clear = React.useCallback(() => {
+    if (selection.disabled) return;
+    selection.clear();
+  }, [selection]);
+
+  const itemState = React.useMemo<SelectableItemState>(() => {
+    return {
+      id,
+      selected,
+      disabled: resolvedDisabled,
+      mode: selection.mode,
+      select,
+      toggle,
+      clear,
+    };
+  }, [clear, id, resolvedDisabled, select, selected, selection.mode, toggle]);
+
+  // IMPORTANT:
+  // Do not pass `children` directly into ButtonBase. ButtonBase also supports function children,
+  // but its function signature receives interaction state, not SelectableItemState.
+  const content = isRenderProp(children) ? children(itemState) : children;
+
+  if (resolvedTrigger === 'manual') {
+    return <>{content}</>;
+  }
+
+  const handlePress = (event: GestureResponderEvent) => {
+    event.stopPropagation();
+    if (resolvedDisabled) return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  const handleLongPress = (event: GestureResponderEvent) => {
+    event.stopPropagation();
+    if (resolvedDisabled) return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  return (
+    <ButtonBase
+      accessibilityRole="button"
+      accessibilityState={{ disabled: resolvedDisabled, selected }}
+      disabled={resolvedDisabled}
+      onLongPress={resolvedTrigger === 'longPress' ? handleLongPress : undefined}
+      onPress={resolvedTrigger === 'press' ? handlePress : undefined}
+    >
+      {content}
+    </ButtonBase>
+  );
+}

package/src/patterns/selection/SelectionProvider.tsx

@@ -0,0 +1,102 @@
+import React from 'react';
+
+import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+import type { SelectionMode, SelectionProviderProps, UseSelectionResult } from './types';
+
+const MISSING_CONTEXT_MESSAGE =
+  'ZORA selection context is missing. Wrap this tree in <SelectionProvider>.';
+
+type SelectionContextValue = UseSelectionResult;
+
+const SelectionContext = React.createContext<SelectionContextValue | null>(null);
+
+function resolveMode(mode: SelectionMode | undefined): SelectionMode {
+  return mode ?? 'single';
+}
+
+function resolveDisabled(disabled: boolean | undefined): boolean {
+  return disabled ?? false;
+}
+
+export function useSelection(): UseSelectionResult {
+  const value = React.useContext(SelectionContext);
+  if (!value) {
+    throw new Error(MISSING_CONTEXT_MESSAGE);
+  }
+
+  return value;
+}
+
+export function SelectionProvider({
+  children,
+  selectedIds,
+  defaultSelectedIds,
+  mode,
+  disabled,
+  onSelectionChange,
+}: SelectionProviderProps) {
+  const resolvedMode = resolveMode(mode);
+  const resolvedDisabled = resolveDisabled(disabled);
+  const isControlled = selectedIds !== undefined;
+
+  const [uncontrolledIds, setUncontrolledIds] = React.useState<readonly string[]>(
+    defaultSelectedIds ?? [],
+  );
+
+  const rawIds = isControlled ? selectedIds : uncontrolledIds;
+  const currentNormalizedIds = normalizeIds(rawIds, resolvedMode);
+
+  const selectedIdSet = React.useMemo(() => new Set(currentNormalizedIds), [currentNormalizedIds]);
+
+  const commitSelectionChange = React.useCallback(
+    (nextNormalizedIds: readonly string[]) => {
+      if (resolvedDisabled) return;
+      if (areIdsEqual(nextNormalizedIds, currentNormalizedIds)) return;
+
+      onSelectionChange?.(nextNormalizedIds);
+
+      if (!isControlled) {
+        setUncontrolledIds(nextNormalizedIds);
+      }
+    },
+    [currentNormalizedIds, isControlled, onSelectionChange, resolvedDisabled],
+  );
+
+  const clear = React.useCallback(() => {
+    commitSelectionChange(normalizeIds(clearIds(), resolvedMode));
+  }, [commitSelectionChange, resolvedMode]);
+
+  const select = React.useCallback(
+    (id: string) => {
+      const nextIds = selectId({ mode: resolvedMode, ids: currentNormalizedIds, id });
+      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
+      commitSelectionChange(nextNormalizedIds);
+    },
+    [commitSelectionChange, currentNormalizedIds, resolvedMode],
+  );
+
+  const toggle = React.useCallback(
+    (id: string) => {
+      const nextIds = toggleId({ mode: resolvedMode, ids: currentNormalizedIds, id });
+      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
+      commitSelectionChange(nextNormalizedIds);
+    },
+    [commitSelectionChange, currentNormalizedIds, resolvedMode],
+  );
+
+  const value = React.useMemo<UseSelectionResult>(() => {
+    return {
+      mode: resolvedMode,
+      disabled: resolvedDisabled,
+      selectedIds: currentNormalizedIds,
+      selectedCount: currentNormalizedIds.length,
+      hasSelection: currentNormalizedIds.length > 0,
+      isSelected: (id: string) => selectedIdSet.has(id),
+      select,
+      toggle,
+      clear,
+    };
+  }, [clear, currentNormalizedIds, resolvedDisabled, resolvedMode, select, selectedIdSet, toggle]);
+
+  return <SelectionContext.Provider value={value}>{children}</SelectionContext.Provider>;
+}

package/src/patterns/selection/index.ts

@@ -0,0 +1,10 @@
+export { SelectableItem } from './SelectableItem';
+export { SelectionProvider, useSelection } from './SelectionProvider';
+export type {
+  SelectableItemProps,
+  SelectableItemState,
+  SelectionMode,
+  SelectionProviderProps,
+  SelectionTrigger,
+  UseSelectionResult,
+} from './types';

package/src/patterns/selection/resolveSelectionNextIds.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+
+import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+import type { SelectionMode } from './types';
+
+describe('resolveSelectionNextIds', () => {
+  test('normalizeIds removes duplicates, preserves order', () => {
+    expect(normalizeIds(['a', 'b', 'a', 'c'], 'multi')).toEqual(['a', 'b', 'c']);
+  });
+
+  test('normalizeIds keeps only first id in single mode', () => {
+    expect(normalizeIds(['a', 'b', 'c'], 'single')).toEqual(['a']);
+  });
+
+  test('normalizeIds treats undefined as empty', () => {
+    expect(normalizeIds(undefined, 'multi')).toEqual([]);
+  });
+
+  test('areIdsEqual compares order', () => {
+    expect(areIdsEqual(['a'], ['a'])).toBeTrue();
+    expect(areIdsEqual(['a'], ['b'])).toBeFalse();
+    expect(areIdsEqual(['a', 'b'], ['a', 'b'])).toBeTrue();
+    expect(areIdsEqual(['a', 'b'], ['b', 'a'])).toBeFalse();
+  });
+
+  test('clearIds returns empty selection', () => {
+    expect(clearIds()).toEqual([]);
+  });
+
+  test('selectId replaces selection in single mode', () => {
+    expect(selectId({ mode: 'single', ids: ['a'], id: 'b' })).toEqual(['b']);
+  });
+
+  test('selectId adds id in multi mode when missing', () => {
+    expect(selectId({ mode: 'multi', ids: ['a'], id: 'b' })).toEqual(['a', 'b']);
+  });
+
+  test('selectId is no-op in multi mode when already selected', () => {
+    const ids = ['a', 'b'];
+    expect(selectId({ mode: 'multi', ids, id: 'b' })).toBe(ids);
+  });
+
+  test('toggleId clears id when already selected (single mode)', () => {
+    expect(toggleId({ mode: 'single', ids: ['a'], id: 'a' })).toEqual([]);
+  });
+
+  test('toggleId selects id when not selected (single mode)', () => {
+    expect(toggleId({ mode: 'single', ids: [], id: 'a' })).toEqual(['a']);
+  });
+
+  test('toggleId toggles membership (multi mode)', () => {
+    expect(toggleId({ mode: 'multi', ids: ['a'], id: 'b' })).toEqual(['a', 'b']);
+    expect(toggleId({ mode: 'multi', ids: ['a', 'b'], id: 'b' })).toEqual(['a']);
+  });
+
+  test('mode-change normalization example', () => {
+    const internalIds = ['a', 'b'];
+    const mode: SelectionMode = 'single';
+    expect(normalizeIds(internalIds, mode)).toEqual(['a']);
+  });
+});

package/src/patterns/selection/resolveSelectionNextIds.ts

@@ -0,0 +1,71 @@
+import type { SelectionMode } from './types';
+
+export function normalizeIds(
+  ids: readonly string[] | undefined,
+  mode: SelectionMode,
+): readonly string[] {
+  const uniqueIds: string[] = [];
+  const seen = new Set<string>();
+
+  for (const id of ids ?? []) {
+    if (seen.has(id)) continue;
+    seen.add(id);
+    uniqueIds.push(id);
+    if (mode === 'single') break;
+  }
+
+  return uniqueIds;
+}
+
+export function areIdsEqual(a: readonly string[], b: readonly string[]): boolean {
+  if (a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) {
+    if (a[index] !== b[index]) return false;
+  }
+
+  return true;
+}
+
+export function clearIds(): readonly string[] {
+  return [];
+}
+
+export function selectId({
+  mode,
+  ids,
+  id,
+}: {
+  mode: SelectionMode;
+  ids: readonly string[];
+  id: string;
+}): readonly string[] {
+  if (mode === 'single') {
+    return [id];
+  }
+
+  if (ids.includes(id)) {
+    return ids;
+  }
+
+  return [...ids, id];
+}
+
+export function toggleId({
+  mode,
+  ids,
+  id,
+}: {
+  mode: SelectionMode;
+  ids: readonly string[];
+  id: string;
+}): readonly string[] {
+  if (ids.includes(id)) {
+    return ids.filter((existingId) => existingId !== id);
+  }
+
+  if (mode === 'single') {
+    return [id];
+  }
+
+  return [...ids, id];
+}

package/src/patterns/selection/types.ts

@@ -0,0 +1,43 @@
+import type React from 'react';
+
+export type SelectionMode = 'single' | 'multi';
+
+export type SelectionTrigger = 'press' | 'longPress' | 'manual';
+
+export interface SelectionProviderProps {
+  children: React.ReactNode;
+  selectedIds?: readonly string[];
+  defaultSelectedIds?: readonly string[];
+  mode?: SelectionMode;
+  disabled?: boolean;
+  onSelectionChange?: (ids: readonly string[]) => void;
+}
+
+export interface UseSelectionResult {
+  mode: SelectionMode;
+  disabled: boolean;
+  selectedIds: readonly string[];
+  selectedCount: number;
+  hasSelection: boolean;
+  isSelected: (id: string) => boolean;
+  select: (id: string) => void;
+  toggle: (id: string) => void;
+  clear: () => void;
+}
+
+export interface SelectableItemState {
+  id: string;
+  selected: boolean;
+  disabled: boolean;
+  mode: SelectionMode;
+  select: () => void;
+  toggle: () => void;
+  clear: () => void;
+}
+
+export interface SelectableItemProps {
+  id: string;
+  trigger?: SelectionTrigger;
+  disabled?: boolean;
+  children: React.ReactNode | ((state: SelectableItemState) => React.ReactNode);
+}

package/src/showcaseCoverage.test.ts

@@ -17,6 +17,7 @@ const IGNORED_DIRECTORY_NAMES = new Set([
 
 const REQUIRED_SHOWCASE_COVERAGE = {
   components: [
+    'AppBar',
     'Avatar',
     'AvatarGroup',
     'Badge',
@@ -85,6 +86,9 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'DisclosureSection',
     'EmptyState',
     'FilterBar',
+    'SelectableItem',
+    'SelectionProvider',
+    'useSelection',
     'List',
     'ListRow',
     'ListSection',

package/src/theme/themeScopeStructure.test.ts

@@ -53,6 +53,7 @@ const scopeGuardDirs = [
 const scopeGuardFiles = scopeGuardDirs.flatMap(collectSourceFiles);
 
 const scopedComponentFiles = [
+  join(srcDir, 'components', 'app-bar', 'AppBar.tsx'),
   join(srcDir, 'components', 'badge', 'Badge.tsx'),
   join(srcDir, 'components', 'button', 'Button.tsx'),
   join(srcDir, 'components', 'card', 'Card.tsx'),
@@ -128,6 +129,7 @@ const scopedComponentFiles = [
 ] as const;
 
 const scopedPropTypeFiles = [
+  join(srcDir, 'components', 'app-bar', 'types.ts'),
   join(srcDir, 'components', 'badge', 'types.ts'),
   join(srcDir, 'components', 'button', 'types.ts'),
   join(srcDir, 'components', 'card', 'types.ts'),