@ankhorage/zora 22.1.4 → 23.1.0

package/src/features/registry/componentMeta.ts

@@ -3,6 +3,7 @@ import { accordionItemMeta } from '../accordion/accordionItemMeta';
 import { accordionMeta } from '../accordion/accordionMeta';
 import { activityIndicatorMeta } from '../activity-indicator/activityIndicatorMeta';
 import { appBarMeta } from '../app-bar/appBarMeta';
+import { authScreenMeta } from '../auth/authScreenMeta';
 import { forgotPasswordFormMeta } from '../auth/forgotPasswordFormMeta';
 import { oauthProviderButtonMeta } from '../auth/oauthProviderButtonMeta';
 import { oauthProviderListMeta } from '../auth/oauthProviderListMeta';
@@ -178,6 +179,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = finalizeFeatureMet
   AppShell: appShellMeta,
   Screen: screenMeta,
   ScreenSection: screenSectionMeta,
+  AuthScreen: authScreenMeta,
   ForgotPasswordForm: forgotPasswordFormMeta,
   OAuthProviderButton: oauthProviderButtonMeta,
   OAuthProviderList: oauthProviderListMeta,

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

@@ -1,29 +1,29 @@
 import { Pressable } from '@ankhorage/surface';
+import type { SelectionIntent } from '@ankhorage/utility/selection';
 import React from 'react';
-import type { GestureResponderEvent } from 'react-native';
+import { type GestureResponderEvent, Platform } from 'react-native';
 
 import type {
   SelectableItemProps,
   SelectableItemState,
   SelectionTrigger,
 } from '../../../../types/selection';
+import { resolveSelectionEventIntent } from '../../application/resolveSelectionEventIntent';
 import { useSelection } from './SelectionProvider';
 
+/*** Resolve the configured selection trigger. */
 function resolveTrigger(trigger: SelectionTrigger | undefined): SelectionTrigger {
   return trigger ?? 'manual';
 }
 
+/*** Narrow render-prop children without changing ordinary React-node children. */
 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.
- *
- 
- */
+/*** Adds selection behavior to arbitrary child content via render props. */
 export function SelectableItem({
   id,
   trigger,
@@ -36,67 +36,50 @@ export function SelectableItem({
   const resolvedDisabled = selection.disabled || disabled;
   const selected = selection.isSelected(id);
 
+  const activate = React.useCallback(
+    (intent: SelectionIntent) => {
+      if (resolvedDisabled || interactionPolicy === 'passive') return;
+      selection.activate(id, intent);
+    },
+    [id, interactionPolicy, resolvedDisabled, selection],
+  );
   const select = React.useCallback(() => {
-    if (resolvedDisabled) return;
-    if (interactionPolicy === 'passive') return;
+    if (resolvedDisabled || interactionPolicy === 'passive') return;
     selection.select(id);
-  }, [id, resolvedDisabled, interactionPolicy, selection]);
-
+  }, [id, interactionPolicy, resolvedDisabled, selection]);
   const toggle = React.useCallback(() => {
-    if (resolvedDisabled) return;
-    if (interactionPolicy === 'passive') return;
+    if (resolvedDisabled || interactionPolicy === 'passive') return;
     selection.toggle(id);
-  }, [id, resolvedDisabled, interactionPolicy, selection]);
-
+  }, [id, interactionPolicy, resolvedDisabled, selection]);
   const clear = React.useCallback(() => {
-    if (selection.disabled) return;
-    if (interactionPolicy === 'passive') return;
+    if (selection.disabled || interactionPolicy === 'passive') return;
     selection.clear();
   }, [interactionPolicy, selection]);
 
-  const itemState = React.useMemo<SelectableItemState>(() => {
-    return {
+  const itemState = React.useMemo<SelectableItemState>(
+    () => ({
       id,
       selected,
       disabled: resolvedDisabled,
       mode: selection.mode,
+      activate,
       select,
       toggle,
       clear,
-    };
-  }, [clear, id, resolvedDisabled, select, selected, selection.mode, toggle]);
+    }),
+    [activate, 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}</>;
 
-  if (resolvedTrigger === 'manual') {
-    return <>{content}</>;
-  }
-
-  const handlePress = (event: GestureResponderEvent) => {
+  const handleActivation = (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);
+    if (resolvedDisabled || interactionPolicy === 'passive') return;
+    selection.activate(
+      id,
+      resolveSelectionEventIntent(event, Platform.OS === 'web' ? 'pointer' : 'touch'),
+    );
   };
 
   return (
@@ -105,8 +88,8 @@ export function SelectableItem({
       accessibilityRole="button"
       accessibilityState={{ disabled: resolvedDisabled, selected }}
       disabled={resolvedDisabled}
-      onLongPress={resolvedTrigger === 'longPress' ? handleLongPress : undefined}
-      onPress={resolvedTrigger === 'press' ? handlePress : undefined}
+      onLongPress={resolvedTrigger === 'longPress' ? handleActivation : undefined}
+      onPress={resolvedTrigger === 'press' ? handleActivation : undefined}
     >
       {content}
     </Pressable>

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

@@ -1,3 +1,4 @@
+import { applySelectionIntent, type SelectionIntent } from '@ankhorage/utility/selection';
 import React from 'react';
 
 import type {
@@ -5,13 +6,7 @@ import type {
   SelectionProviderProps,
   UseSelectionResult,
 } from '../../../../types/selection';
-import {
-  areIdsEqual,
-  clearIds,
-  normalizeIds,
-  selectId,
-  toggleId,
-} from '../../utils/resolveSelectionNextIds';
+import { areIdsEqual, clearIds, normalizeIds, selectId } from '../../utils/resolveSelectionNextIds';
 
 const MISSING_CONTEXT_MESSAGE =
   'ZORA selection context is missing. Wrap this tree in <SelectionProvider>.';
@@ -30,21 +25,14 @@ function resolveDisabled(disabled: boolean | undefined): boolean {
   return disabled ?? false;
 }
 
-/***
- * Accesses selection state provided by `SelectionProvider`.
- */
+/*** Accesses selection state provided by `SelectionProvider`. */
 export function useSelection(): UseSelectionResult {
   const value = React.use(SelectionContext);
-  if (!value) {
-    throw new Error(MISSING_CONTEXT_MESSAGE);
-  }
-
+  if (!value) throw new Error(MISSING_CONTEXT_MESSAGE);
   return value;
 }
 
-/***
- * Provides selection state for building selectable lists and grids.
- */
+/*** Provides selection state for building selectable lists and grids. */
 export function SelectionProvider({
   children,
   selectedIds,
@@ -57,27 +45,20 @@ export function SelectionProvider({
   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 (resolvedDisabled || interactionPolicy === 'passive') return;
       if (areIdsEqual(nextNormalizedIds, currentNormalizedIds)) return;
-
       onSelectionChange?.(nextNormalizedIds);
-
-      if (!isControlled) {
-        setUncontrolledIds(nextNormalizedIds);
-      }
+      if (!isControlled) setUncontrolledIds(nextNormalizedIds);
     },
     [currentNormalizedIds, interactionPolicy, isControlled, onSelectionChange, resolvedDisabled],
   );
@@ -89,34 +70,52 @@ export function SelectionProvider({
   const select = React.useCallback(
     (id: string) => {
       const nextIds = selectId({ mode: resolvedMode, ids: currentNormalizedIds, id });
-      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
-      commitSelectionChange(nextNormalizedIds);
+      commitSelectionChange(normalizeIds(nextIds, resolvedMode));
     },
     [commitSelectionChange, currentNormalizedIds, resolvedMode],
   );
 
   const toggle = React.useCallback(
     (id: string) => {
-      const nextIds = toggleId({ mode: resolvedMode, ids: currentNormalizedIds, id });
-      const nextNormalizedIds = normalizeIds(nextIds, resolvedMode);
-      commitSelectionChange(nextNormalizedIds);
+      const nextIds = applySelectionIntent(currentNormalizedIds, id, 'toggle');
+      commitSelectionChange(normalizeIds(nextIds, resolvedMode));
     },
     [commitSelectionChange, currentNormalizedIds, resolvedMode],
   );
 
-  const value = React.useMemo<UseSelectionResult>(() => {
-    return {
+  const activate = React.useCallback(
+    (id: string, intent: SelectionIntent) => {
+      const effectiveIntent = resolvedMode === 'single' ? 'replace' : intent;
+      const nextIds = applySelectionIntent(currentNormalizedIds, id, effectiveIntent);
+      commitSelectionChange(normalizeIds(nextIds, resolvedMode));
+    },
+    [commitSelectionChange, currentNormalizedIds, resolvedMode],
+  );
+
+  const value = React.useMemo<UseSelectionResult>(
+    () => ({
       mode: resolvedMode,
       disabled: resolvedDisabled,
       selectedIds: currentNormalizedIds,
       selectedCount: currentNormalizedIds.length,
       hasSelection: currentNormalizedIds.length > 0,
       isSelected: (id: string) => selectedIdSet.has(id),
+      activate,
       select,
       toggle,
       clear,
-    };
-  }, [clear, currentNormalizedIds, resolvedDisabled, resolvedMode, select, selectedIdSet, toggle]);
+    }),
+    [
+      activate,
+      clear,
+      currentNormalizedIds,
+      resolvedDisabled,
+      resolvedMode,
+      select,
+      selectedIdSet,
+      toggle,
+    ],
+  );
 
   return <SelectionContext value={value}>{children}</SelectionContext>;
 }

package/src/features/selection/application/resolveSelectionEventIntent.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveSelectionEventIntent } from './resolveSelectionEventIntent';
+
+describe('resolveSelectionEventIntent', () => {
+  test('replaces for an unmodified desktop pointer event', () => {
+    expect(resolveSelectionEventIntent({}, 'pointer')).toBe('replace');
+  });
+
+  test('toggles for Command and Control modifiers', () => {
+    expect(resolveSelectionEventIntent({ metaKey: true }, 'pointer')).toBe('toggle');
+    expect(resolveSelectionEventIntent({ nativeEvent: { ctrlKey: true } }, 'pointer')).toBe(
+      'toggle',
+    );
+  });
+
+  test('toggles pointer events reported as touch', () => {
+    expect(
+      resolveSelectionEventIntent({ originalEvent: { pointerType: 'touch' } }, 'pointer'),
+    ).toBe('toggle');
+  });
+
+  test('toggles renderer touch events without pointerType', () => {
+    expect(
+      resolveSelectionEventIntent(
+        { originalEvent: { type: 'touchend', changedTouches: [] } },
+        'pointer',
+      ),
+    ).toBe('toggle');
+  });
+
+  test('toggles native touch fallback without modifier data', () => {
+    expect(resolveSelectionEventIntent({}, 'touch')).toBe('toggle');
+  });
+});

package/src/features/selection/application/resolveSelectionEventIntent.ts

@@ -0,0 +1,55 @@
+import {
+  type InteractionModifiers,
+  resolveSelectionIntent,
+  type SelectionActivationKind,
+  type SelectionInteractionInput,
+} from '@ankhorage/utility/interaction';
+import { isRecord } from '@ankhorage/utility/object';
+import type { SelectionIntent } from '@ankhorage/utility/selection';
+
+/*** Normalize DOM, React Native, and renderer events into one semantic selection intent. */
+export function resolveSelectionEventIntent(
+  event: unknown,
+  fallbackKind: SelectionActivationKind,
+): SelectionIntent {
+  const source = readEventSource(event);
+  const kind: SelectionActivationKind = isTouchActivation(source) ? 'touch' : fallbackKind;
+  const sourceModifiers = readInteractionModifiers(source);
+  const wrapperModifiers = readInteractionModifiers(event);
+  const input: SelectionInteractionInput = {
+    kind,
+    modifiers: {
+      altKey: sourceModifiers.altKey === true || wrapperModifiers.altKey === true,
+      ctrlKey: sourceModifiers.ctrlKey === true || wrapperModifiers.ctrlKey === true,
+      metaKey: sourceModifiers.metaKey === true || wrapperModifiers.metaKey === true,
+      shiftKey: sourceModifiers.shiftKey === true || wrapperModifiers.shiftKey === true,
+    },
+  };
+  return resolveSelectionIntent(input);
+}
+
+/*** Prefer one nested native/renderer event while preserving structural event compatibility. */
+function readEventSource(event: unknown): Readonly<Record<string, unknown>> {
+  if (!isRecord(event)) return {};
+  if (isRecord(event.originalEvent)) return event.originalEvent;
+  if (isRecord(event.nativeEvent)) return event.nativeEvent;
+  return event;
+}
+
+/*** Recognize pointer and native/browser touch event shapes without depending on platform event types. */
+function isTouchActivation(source: Readonly<Record<string, unknown>>): boolean {
+  if (source.pointerType === 'touch') return true;
+  if (typeof source.type === 'string' && source.type.startsWith('touch')) return true;
+  return 'touches' in source || 'changedTouches' in source;
+}
+
+/*** Read known modifiers explicitly so arbitrary event properties never become dynamic input keys. */
+function readInteractionModifiers(value: unknown): InteractionModifiers {
+  if (!isRecord(value)) return {};
+  return {
+    altKey: value.altKey === true,
+    ctrlKey: value.ctrlKey === true,
+    metaKey: value.metaKey === true,
+    shiftKey: value.shiftKey === true,
+  };
+}

package/src/features/selection/public.ts

@@ -8,3 +8,5 @@ export type {
 } from '../../types/selection';
 export { SelectableItem } from './adapters/inbound/SelectableItem';
 export { SelectionProvider, useSelection } from './adapters/inbound/SelectionProvider';
+export { resolveSelectionEventIntent } from './application/resolveSelectionEventIntent';
+export type { SelectionIntent } from '@ankhorage/utility/selection';

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

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'bun:test';
 
 import type { SelectionMode } from '../../../types/selection';
-import { areIdsEqual, clearIds, normalizeIds, selectId, toggleId } from './resolveSelectionNextIds';
+import { areIdsEqual, clearIds, normalizeIds, selectId } from './resolveSelectionNextIds';
 
 describe('resolveSelectionNextIds', () => {
   test('normalizeIds removes duplicates, preserves order', () => {
@@ -40,19 +40,6 @@ describe('resolveSelectionNextIds', () => {
     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';

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

@@ -1,5 +1,6 @@
 import type { SelectionMode } from '../../../types/selection';
 
+/*** Normalize selected ids to stable unique membership within the configured selection mode. */
 export function normalizeIds(
   ids: readonly string[] | undefined,
   mode: SelectionMode,
@@ -17,6 +18,7 @@ export function normalizeIds(
   return uniqueIds;
 }
 
+/*** Compare ordered selection ids without allocating replacement arrays. */
 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) {
@@ -26,10 +28,12 @@ export function areIdsEqual(a: readonly string[], b: readonly string[]): boolean
   return true;
 }
 
+/*** Produce the canonical empty selection. */
 export function clearIds(): readonly string[] {
   return [];
 }
 
+/*** Ensure one id is selected while preserving multi-selection membership. */
 export function selectId({
   mode,
   ids,
@@ -39,33 +43,7 @@ export function selectId({
   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];
-  }
-
+  if (mode === 'single') return [id];
+  if (ids.includes(id)) return ids;
   return [...ids, id];
 }

package/src/features/tree-view/adapters/inbound/TreeItem.tsx

@@ -1,4 +1,7 @@
+import { Pressable } from '@ankhorage/surface';
+import type { SelectionIntent } from '@ankhorage/utility/selection';
 import React from 'react';
+import { Platform } from 'react-native';
 
 import type { ZoraBaseProps } from '../../../../types/base';
 import type { TreeItemNode, TreeItemRenderProps } from '../../../../types/tree-view';
@@ -6,15 +9,16 @@ import { IconButton } from '../../../button/public';
 import { Icon } from '../../../icon/public';
 import { View } from '../../../layout/public';
 import { ListItem } from '../../../list/public';
+import { resolveSelectionEventIntent } from '../../../selection/public';
 import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
 
 interface TreeItemProps<TId extends string = string> extends ZoraBaseProps {
   node: TreeItemNode<TId>;
   depth: number;
   expansionIndicator: 'chevron' | 'folder';
-  selectedId?: TId;
+  selectedIds: readonly TId[];
   expandedIds: readonly TId[];
-  onSelect?: (id: TId) => void;
+  onSelect?: (id: TId, intent: SelectionIntent) => void;
   onToggleExpand: (id: TId) => void;
   renderItem?: (props: TreeItemRenderProps<TId>) => React.ReactNode;
 }
@@ -26,7 +30,7 @@ function TreeItemInner<TId extends string = string>({
   node,
   depth,
   expansionIndicator,
-  selectedId,
+  selectedIds,
   expandedIds,
   onSelect,
   onToggleExpand,
@@ -36,7 +40,7 @@ function TreeItemInner<TId extends string = string>({
 }: TreeItemProps<TId>) {
   const hasChildren = node.children !== undefined && node.children.length > 0;
   const isExpanded = expandedIds.includes(node.id);
-  const isSelected = selectedId === node.id;
+  const isSelected = selectedIds.includes(node.id);
 
   /*** Compose custom content or the selectable row independently of the expansion control. */
   const renderContent = () => {
@@ -62,10 +66,22 @@ function TreeItemInner<TId extends string = string>({
       trailing: node.actions,
     };
 
-    return onSelect === undefined ? (
-      <ListItem {...listItemProps} />
-    ) : (
-      <ListItem {...listItemProps} onPress={() => onSelect(node.id)} />
+    if (onSelect === undefined) return <ListItem {...listItemProps} />;
+    return (
+      <Pressable
+        accessibilityRole="button"
+        accessibilityState={{ disabled: node.disabled, selected: isSelected }}
+        disabled={node.disabled}
+        interactionPolicy={interactionPolicy}
+        onPress={(event) =>
+          onSelect(
+            node.id,
+            resolveSelectionEventIntent(event, Platform.OS === 'web' ? 'pointer' : 'touch'),
+          )
+        }
+      >
+        <ListItem {...listItemProps} />
+      </Pressable>
     );
   };
 
@@ -111,7 +127,7 @@ function TreeItemInner<TId extends string = string>({
               onSelect={onSelect}
               onToggleExpand={onToggleExpand}
               renderItem={renderItem}
-              selectedId={selectedId}
+              selectedIds={selectedIds}
             />
           ))}
         </View>

package/src/features/tree-view/adapters/inbound/TreeView.tsx

@@ -6,12 +6,12 @@ import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThem
 import { toggleExpandedIds } from '../../utils/toggleExpandedIds';
 import { TreeItem } from './TreeItem';
 
-/*** Render the themed TreeView while supporting controlled or internal expansion state. */
+/*** Render the themed TreeView while supporting controlled selection and expansion state. */
 function TreeViewInner<TId extends string = string>({
   themeId: _themeId,
   mode: _mode,
   nodes,
-  selectedId,
+  selectedIds = [],
   expandedIds: controlledExpandedIds,
   defaultExpandedIds,
   onSelect,
@@ -32,9 +32,7 @@ function TreeViewInner<TId extends string = string>({
     if (interactionPolicy === 'passive') return;
     const nextExpandedIds = toggleExpandedIds(expandedIds, id);
 
-    if (!isControlled) {
-      setInternalExpandedIds(nextExpandedIds);
-    }
+    if (!isControlled) setInternalExpandedIds(nextExpandedIds);
     onExpandedChange?.(nextExpandedIds);
   };
 
@@ -50,7 +48,7 @@ function TreeViewInner<TId extends string = string>({
           onSelect={onSelect}
           onToggleExpand={handleToggleExpand}
           renderItem={renderItem}
-          selectedId={selectedId}
+          selectedIds={selectedIds}
           interactionPolicy={interactionPolicy}
         />
       ))}