@ankhorage/zora 22.1.3 → 23.0.0

package/src/features/graph-view/adapters/inbound/web-artifact/GraphNodeOverlay.tsx

@@ -1,3 +1,4 @@
+import type { SelectionIntent } from '@ankhorage/utility/selection';
 import React from 'react';
 
 import type {
@@ -7,12 +8,17 @@ import type {
   GraphViewRenderedNode,
   GraphViewSize,
 } from '../../../../../types/graph-view';
+import { resolveSelectionEventIntent } from '../../../../selection/application/resolveSelectionEventIntent';
 
 interface GraphNodeOverlayProps {
   readonly nodes: readonly GraphViewNode[];
   readonly renderedNodes: readonly GraphViewRenderedNode[];
   readonly renderNode: (context: GraphViewNodeRenderContext) => React.ReactNode;
-  readonly onNodeEvent: (id: string, type: GraphViewElementEventType) => void;
+  readonly onNodeEvent: (
+    id: string,
+    type: GraphViewElementEventType,
+    selectionIntent?: SelectionIntent,
+  ) => void;
   readonly onNodeSize: (id: string, size: GraphViewSize) => void;
 }
 
@@ -89,7 +95,9 @@ function MeasuredGraphNode(props: MeasuredGraphNodeProps) {
         transform: `translate(-50%, -50%) scale(${renderedNode.zoom})`,
         transformOrigin: 'center',
       }}
-      onClick={() => props.onNodeEvent(node.id, 'press')}
+      onPointerUp={(event) =>
+        props.onNodeEvent(node.id, 'press', resolveSelectionEventIntent(event, 'pointer'))
+      }
       onDoubleClick={() => props.onNodeEvent(node.id, 'double-press')}
       onMouseEnter={() => props.onNodeEvent(node.id, 'pointer-enter')}
       onMouseLeave={() => props.onNodeEvent(node.id, 'pointer-leave')}

package/src/features/graph-view/adapters/inbound/web-artifact/GraphView.tsx

@@ -48,7 +48,9 @@ export function GraphView(props: GraphViewProps) {
           nodes={props.nodes}
           renderedNodes={renderedNodes}
           renderNode={props.renderNode}
-          onNodeEvent={(id, type) => runtimeRef.current?.handleOverlayNodeEvent(id, type)}
+          onNodeEvent={(id, type, selectionIntent) =>
+            runtimeRef.current?.handleOverlayNodeEvent(id, type, selectionIntent)
+          }
           onNodeSize={(id, size) => runtimeRef.current?.setNodeSize(id, size)}
         />
       ) : null}

package/src/features/graph-view/adapters/inbound/web-artifact/bindGraphEvents.ts

@@ -3,8 +3,10 @@ import type { Core, EventObject } from 'cytoscape';
 import type {
   GraphViewCallbacks,
   GraphViewController,
+  GraphViewElementEvent,
   GraphViewElementEventType,
 } from '../../../../../types/graph-view';
+import { resolveSelectionEventIntent } from '../../../../selection/application/resolveSelectionEventIntent';
 
 /*** Bind stable Cytoscape events that always read the latest React callbacks. */
 export function bindGraphEvents(
@@ -46,10 +48,11 @@ function bindElementEvents(
     const handler = (event: EventObject) => {
       const target: unknown = event.target;
       if (!isGraphEventTarget(target)) return;
-      emitElementEvent(callbacksRef.current, selector, {
-        id: target.id(),
-        type,
-      });
+      emitElementEvent(
+        callbacksRef.current,
+        selector,
+        createElementEvent(event, target.id(), type),
+      );
       onRuntimeChange();
     };
     cy.on(cytoscapeEvent, selector, handler);
@@ -57,6 +60,20 @@ function bindElementEvents(
   });
 }
 
+/*** Translate one renderer event into the engine-neutral public event contract. */
+function createElementEvent(
+  event: EventObject,
+  id: string,
+  type: GraphViewElementEventType,
+): GraphViewElementEvent {
+  if (type !== 'press') return { id, type };
+  return {
+    id,
+    type,
+    selectionIntent: resolveSelectionEventIntent(event, 'pointer'),
+  };
+}
+
 /*** Return whether a Cytoscape event target exposes the element identifier contract. */
 function isGraphEventTarget(value: unknown): value is GraphEventTarget {
   return (
@@ -72,7 +89,7 @@ interface GraphEventTarget {
 function emitElementEvent(
   callbacks: GraphViewCallbacks,
   selector: ElementSelector,
-  event: { readonly id: string; readonly type: GraphViewElementEventType },
+  event: GraphViewElementEvent,
 ) {
   if (selector === 'node') {
     callbacks.onNodeEvent?.(event);

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphRuntime.test.ts

@@ -172,6 +172,27 @@ test('preserves selection and positions through hover presentation updates witho
   }
 });
 
+test('forwards semantic selection intent from rich-node press events', async () => {
+  const ready = Promise.withResolvers<GraphViewController>();
+  const events: GraphViewElementEvent[] = [];
+  const runtime = createGraphRuntime(undefined, {
+    current: { onReady: ready.resolve, onNodeEvent: (event) => events.push(event) },
+  });
+  try {
+    runtime.update({
+      nodes: [{ id: 'a' }],
+      edges: [],
+      layout: 'grid',
+      richNodeRendering: false,
+    });
+    await ready.promise;
+    runtime.handleOverlayNodeEvent('a', 'press', 'toggle');
+    expect(events.at(-1)).toEqual({ id: 'a', type: 'press', selectionIntent: 'toggle' });
+  } finally {
+    runtime.destroy();
+  }
+});
+
 test('settles the pending initial layout when presentation changes before readiness', async () => {
   const ready = Promise.withResolvers<GraphViewController>();
   const calls = { ready: 0, sort: 0 };

package/src/features/graph-view/adapters/inbound/web-artifact/createGraphRuntime.ts

@@ -1,3 +1,4 @@
+import type { SelectionIntent } from '@ankhorage/utility/selection';
 import cytoscape, { type Core, type CytoscapeOptions } from 'cytoscape';
 
 import type {
@@ -30,7 +31,11 @@ type RenderedNodeListener = (nodes: readonly GraphViewRenderedNode[]) => void;
 
 export interface GraphRuntime {
   destroy(): void;
-  handleOverlayNodeEvent(id: string, type: GraphViewElementEventType): void;
+  handleOverlayNodeEvent(
+    id: string,
+    type: GraphViewElementEventType,
+    selectionIntent?: SelectionIntent,
+  ): void;
   setNodeSize(id: string, size: GraphViewSize): void;
   setSelectedNodeIds(nodeIds: readonly string[] | undefined): void;
   subscribeRenderedNodes(listener: RenderedNodeListener): () => void;
@@ -80,7 +85,8 @@ export function createGraphRuntime(
 
   return {
     destroy: () => destroyRuntime(state),
-    handleOverlayNodeEvent: (id, type) => handleOverlayNodeEvent(state, id, type),
+    handleOverlayNodeEvent: (id, type, selectionIntent) =>
+      handleOverlayNodeEvent(state, id, type, selectionIntent),
     setNodeSize: (id, size) => setNodeSize(state, id, size),
     setSelectedNodeIds: (nodeIds) => setSelectedNodeIds(state, nodeIds),
     subscribeRenderedNodes: (listener) => subscribeRenderedNodes(state, listener),
@@ -401,11 +407,12 @@ function handleOverlayNodeEvent(
   state: GraphRuntimeState,
   id: string,
   type: GraphViewElementEventType,
+  selectionIntent?: SelectionIntent,
 ) {
   if (type === 'pointer-enter') state.hoveredNodeIds.add(id);
   if (type === 'pointer-leave') state.hoveredNodeIds.delete(id);
   if (type === 'press') state.cy.getElementById(id).select();
-  state.callbacksRef.current.onNodeEvent?.({ id, type });
+  state.callbacksRef.current.onNodeEvent?.({ id, type, selectionIntent });
   emitRenderedNodes(state);
 }
 

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