@ankhorage/zora 18.0.1 → 19.0.1

package/src/features/selection/adapters/inbound/SelectableItem.tsx

@@ -0,0 +1,114 @@
+import { Pressable } from '@ankhorage/surface';
+import React from 'react';
+import type { GestureResponderEvent } from 'react-native';
+
+import type {
+  SelectableItemProps,
+  SelectableItemState,
+  SelectionTrigger,
+} from '../../../../types/selection';
+import { useSelection } from './SelectionProvider';
+
+function resolveTrigger(trigger: SelectionTrigger | undefined): SelectionTrigger {
+  return trigger ?? 'manual';
+}
+
+function isRenderProp(
+  children: SelectableItemProps['children'],
+): children is (state: SelectableItemState) => React.ReactNode {
+  return typeof children === 'function';
+}
+
+/***
+ * Adds selection behavior to arbitrary child content via render props.
+ *
+ 
+ */
+export function SelectableItem({
+  id,
+  trigger,
+  disabled = false,
+  interactionPolicy,
+  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;
+    if (interactionPolicy === 'passive') return;
+    selection.select(id);
+  }, [id, resolvedDisabled, interactionPolicy, selection]);
+
+  const toggle = React.useCallback(() => {
+    if (resolvedDisabled) return;
+    if (interactionPolicy === 'passive') return;
+    selection.toggle(id);
+  }, [id, resolvedDisabled, interactionPolicy, selection]);
+
+  const clear = React.useCallback(() => {
+    if (selection.disabled) return;
+    if (interactionPolicy === 'passive') return;
+    selection.clear();
+  }, [interactionPolicy, 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 Pressable. Pressable 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 (interactionPolicy === 'passive') return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  const handleLongPress = (event: GestureResponderEvent) => {
+    event.stopPropagation();
+    if (resolvedDisabled) return;
+    if (interactionPolicy === 'passive') return;
+    if (selection.mode === 'single') {
+      selection.select(id);
+      return;
+    }
+
+    selection.toggle(id);
+  };
+
+  return (
+    <Pressable
+      interactionPolicy={interactionPolicy}
+      accessibilityRole="button"
+      accessibilityState={{ disabled: resolvedDisabled, selected }}
+      disabled={resolvedDisabled}
+      onLongPress={resolvedTrigger === 'longPress' ? handleLongPress : undefined}
+      onPress={resolvedTrigger === 'press' ? handlePress : undefined}
+    >
+      {content}
+    </Pressable>
+  );
+}

package/src/features/selection/adapters/inbound/SelectionProvider.tsx

@@ -0,0 +1,122 @@
+import React from 'react';
+
+import type {
+  SelectionMode,
+  SelectionProviderProps,
+  UseSelectionResult,
+} from '../../../../types/selection';
+import {
+  areIdsEqual,
+  clearIds,
+  normalizeIds,
+  selectId,
+  toggleId,
+} from '../../utils/resolveSelectionNextIds';
+
+const MISSING_CONTEXT_MESSAGE =
+  'ZORA selection context is missing. Wrap this tree in <SelectionProvider>.';
+
+type SelectionContextValue = UseSelectionResult;
+
+const SelectionContext = React.createContext<SelectionContextValue | null>(null);
+
+/*** Resolve the effective selection mode. */
+function resolveMode(mode: SelectionMode | undefined): SelectionMode {
+  return mode ?? 'single';
+}
+
+/*** Resolve the effective disabled state. */
+function resolveDisabled(disabled: boolean | undefined): boolean {
+  return disabled ?? false;
+}
+
+/***
+ * Accesses selection state provided by `SelectionProvider`.
+ */
+export function useSelection(): UseSelectionResult {
+  const value = React.use(SelectionContext);
+  if (!value) {
+    throw new Error(MISSING_CONTEXT_MESSAGE);
+  }
+
+  return value;
+}
+
+/***
+ * Provides selection state for building selectable lists and grids.
+ */
+export function SelectionProvider({
+  children,
+  selectedIds,
+  defaultSelectedIds,
+  mode,
+  disabled,
+  onSelectionChange,
+  interactionPolicy,
+}: 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 (interactionPolicy === 'passive') return;
+      if (areIdsEqual(nextNormalizedIds, currentNormalizedIds)) return;
+
+      onSelectionChange?.(nextNormalizedIds);
+
+      if (!isControlled) {
+        setUncontrolledIds(nextNormalizedIds);
+      }
+    },
+    [currentNormalizedIds, interactionPolicy, 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 value={value}>{children}</SelectionContext>;
+}

package/src/features/selection/meta.ts

@@ -0,0 +1,21 @@
+import type { ZoraComponentMeta } from '../authoring';
+
+const SELECTION_NOTE = 'Selection pattern component; not represented as a manifest node in v1.';
+
+export const selectableItemMeta = {
+  name: 'SelectableItem',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: SELECTION_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;
+
+export const selectionProviderMeta = {
+  name: 'SelectionProvider',
+  category: 'pattern',
+  directManifestNode: false,
+  allowedChildren: [],
+  note: SELECTION_NOTE,
+  props: {},
+} as const satisfies ZoraComponentMeta;

package/src/features/selection/public.ts

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

package/src/features/selection/utils/resolveSelectionNextIds.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { SelectionMode } from '../../../types/selection';
+import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+
+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/features/selection/utils/resolveSelectionNextIds.ts

@@ -0,0 +1,71 @@
+import type { SelectionMode } from '../../../types/selection';
+
+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.at(index) !== b.at(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/features/skeleton/adapters/inbound/Skeleton.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonProps } from '../../../../types/skeleton';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 
 function SkeletonInner({
   themeId: _themeId,

package/src/features/skeleton/adapters/inbound/SkeletonCard.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonCardProps } from '../../../../types/skeleton';
 import { ButtonGroup } from '../../../button/public';
 import { Card } from '../../../card/public';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 import { SkeletonText } from './SkeletonText';
 

package/src/features/skeleton/adapters/inbound/SkeletonList.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonListProps } from '../../../../types/skeleton';
 import { List, type ListItemProps } from '../../../list/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 import { SkeletonText } from './SkeletonText';
 

package/src/features/skeleton/adapters/inbound/SkeletonText.tsx

@@ -1,8 +1,8 @@
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SkeletonTextProps } from '../../../../types/skeleton';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { Skeleton } from './Skeleton';
 
 function clampLines(lines: number): number {

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

@@ -1,6 +1,6 @@
 import { expect, test } from 'bun:test';
 
-import { ZORA_COMPONENT_META } from '../../metadata/componentMeta';
+import { ZORA_COMPONENT_META } from '../authoring/componentMeta';
 
 test('skeletons support direct authoring and automatic feature loading states', async () => {
   const [dataTableSource, publicSource] = await Promise.all([

package/src/features/skeleton/skeletonMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const skeletonMeta = {
   name: 'Skeleton',

package/src/features/surface/adapters/inbound/Surface.tsx

@@ -1,8 +1,8 @@
 import { Surface as SurfaceSurface } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { SurfaceProps } from '../../../../types/surface';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Adapts the themed Surface Surface primitive to ZORA scope and interaction props. */
 export const Surface = withZoraThemeScope(SurfaceInner);

package/src/features/surface/surfaceMeta.ts

@@ -1,5 +1,5 @@
-import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 import { LAYOUT_PROPS } from '../layout/constants';
 
 export const surfaceMeta = {

package/src/features/tabs/adapters/inbound/Tab.tsx

@@ -1,8 +1,8 @@
 import { Tab as SurfaceTab } from '@ankhorage/surface';
 import React from 'react';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TabsInteractionPolicyContext } from '../../composition/TabsInteractionPolicyContext';
 
 /*** Renders one labeled selectable tab backed by Surface accessibility semantics. */

package/src/features/tabs/adapters/inbound/TabList.tsx

@@ -1,7 +1,7 @@
 import { TabList as SurfaceTabList } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabListProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders the accessible list of tabs for a Tabs composition. */
 export const TabList = withZoraThemeScope(TabListInner);

package/src/features/tabs/adapters/inbound/TabPanel.tsx

@@ -1,7 +1,7 @@
 import { TabPanel as SurfaceTabPanel } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabPanelProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 /*** Renders content associated with one selected Tab. */
 export const TabPanel = withZoraThemeScope(TabPanelInner);

package/src/features/tabs/adapters/inbound/Tabs.tsx

@@ -1,7 +1,7 @@
 import { Tabs as SurfaceTabs } from '@ankhorage/surface';
 
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { TabsProps } from '../../../../types/tabs';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 import { TabsInteractionPolicyContext } from '../../composition/TabsInteractionPolicyContext';
 
 /*** Provides accessible tab state and interaction policy through the Surface Tabs primitive. */

package/src/features/tabs/tabListMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabListMeta = {
   name: 'TabList',

package/src/features/tabs/tabMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabMeta = {
   name: 'Tab',

package/src/features/tabs/tabPanelMeta.ts

@@ -1,5 +1,5 @@
-import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
 
 export const tabPanelMeta = {
   name: 'TabPanel',

package/src/features/tabs/tabsMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const tabsMeta = {
   name: 'Tabs',

package/src/features/theme/ThemeModeToggle.meta.ts

@@ -0,0 +1,29 @@
+import type { ZoraComponentMeta } from '../authoring';
+
+export const themeModeToggleMeta = {
+  name: 'ThemeModeToggle',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Theme mode toggle',
+    defaultProps: {
+      size: 'm',
+    },
+  },
+  props: {
+    disabled: {
+      type: 'boolean',
+      category: 'Behavior',
+      label: 'Disabled',
+      default: false,
+    },
+    size: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Size',
+      enum: ['s', 'm', 'l'],
+      default: 'm',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/theme/adapters/inbound/ThemeModeToggle.tsx

@@ -0,0 +1,28 @@
+import type { ThemeModeToggleProps } from '../../../../types/theme-mode-toggle';
+import { IconButton } from '../../../button/public';
+import { useZoraTheme } from '../../composition/useZoraTheme';
+import { resolveThemeModeToggleState } from '../../utils/resolveThemeModeToggleState';
+
+export function ThemeModeToggle({
+  disabled,
+  interactionPolicy,
+  size = 'm',
+  testID,
+}: ThemeModeToggleProps) {
+  const { mode, setMode } = useZoraTheme();
+  const state = resolveThemeModeToggleState(mode);
+
+  return (
+    <IconButton
+      color="neutral"
+      disabled={disabled}
+      icon={{ name: state.iconName }}
+      interactionPolicy={interactionPolicy}
+      label={state.label}
+      onPress={() => setMode(state.nextMode)}
+      size={size}
+      testID={testID}
+      variant="ghost"
+    />
+  );
+}

package/src/features/theme/adapters/inbound/ZoraProvider.tsx

@@ -0,0 +1,36 @@
+import { ThemeProvider } from '@ankhorage/surface';
+import React from 'react';
+
+import type { ZoraProviderProps } from '../../../../types/provider';
+import { createZoraThemeConfig } from '../../application/use-cases/createZoraThemeConfig';
+import { ZoraRuntimeCapabilities } from '../../composition/ZoraRuntimeCapabilities';
+import { ZoraThemeRuntimeContext } from '../../composition/ZoraThemeRuntimeContext';
+import { zoraDefaultTheme } from '../../zoraDefaultTheme';
+
+export type { ZoraProviderProps, ZoraToastCapability } from '../../../../types/provider';
+
+/*** Installs the core ZORA theme runtime and explicitly enabled optional capabilities. */
+export function ZoraProvider({
+  bottomSheet = false,
+  children,
+  theme = zoraDefaultTheme,
+  themeConfig,
+  initialMode = 'light',
+  toast = false,
+}: ZoraProviderProps) {
+  const resolvedConfig = React.useMemo(
+    () => themeConfig ?? createZoraThemeConfig(theme),
+    [theme, themeConfig],
+  );
+  const runtimeValue = React.useMemo(() => ({ themeId: resolvedConfig.id }), [resolvedConfig.id]);
+
+  return (
+    <ZoraThemeRuntimeContext value={runtimeValue}>
+      <ThemeProvider initialConfig={resolvedConfig} initialMode={initialMode}>
+        <ZoraRuntimeCapabilities bottomSheet={bottomSheet} toast={toast}>
+          {children}
+        </ZoraRuntimeCapabilities>
+      </ThemeProvider>
+    </ZoraThemeRuntimeContext>
+  );
+}