@userflow-tech/react-native 0.1.0

package/src/anchors/AutoAnchorRegistry.ts

@@ -0,0 +1,439 @@
+import type { SemanticRole, SemanticSegment, SiblingDescriptor } from '@userflow-tech/protocol';
+import type { MutableRefObject, RefObject } from 'react';
+
+/**
+ * Multi-instance auto-anchor registry for Stage 3.
+ *
+ * Separate from {@link AnchorRegistry} (manual `useUserflowAnchor` / Tier 0).
+ * Each mounted host is a distinct instance indexed by registry key, template
+ * path, and developer ids so a later scored matcher can rank candidates.
+ */
+
+export type AutoAnchorRef = RefObject<unknown> | MutableRefObject<unknown>;
+
+export type AutoAnchorListener = () => void;
+
+/** Build-time descriptor stamped by `@userflow-tech/babel-plugin` (full or expanded compact). */
+export interface BuildTimeHints {
+  /** Canonical structural path (IDs replace ordinals when present). */
+  ufid: string;
+  /** Build-local alias key (`uf_<hash>` of templatePath). */
+  nativeId: string;
+  structuralPath?: string;
+  templatePath?: string;
+  childText?: string;
+  childShape?: string;
+  iconName?: string;
+  imageSrc?: string;
+  literalTestId?: string;
+  literalLabel?: string;
+  literalUserflowId?: string;
+  ordinal?: number;
+  siblingIndex?: number;
+  role?: SemanticRole;
+  ancestors?: SemanticSegment[];
+}
+
+export interface AutoAnchorInstance {
+  instanceId: string;
+  registryKey: string;
+  ref: AutoAnchorRef;
+  kind: string;
+  role: SemanticRole;
+  isPressable: boolean;
+  templatePath: string;
+  structuralPath: string;
+  instanceScope?: string;
+  manualId?: string;
+  userflowId?: string;
+  testID?: string;
+  nativeID?: string;
+  childText?: string;
+  accessibilityLabel?: string;
+  childShape?: string;
+  iconName?: string;
+  imageSrc?: string;
+  ancestors: SemanticSegment[];
+  ordinal?: number;
+  siblingIndex?: number;
+  parentInstanceId?: string;
+  childInstanceIds: string[];
+  ambiguous: boolean;
+}
+
+export interface RegisterInstanceInput {
+  registryKey: string;
+  ref: AutoAnchorRef;
+  kind: string;
+  hints?: BuildTimeHints | null;
+  instanceScope?: string | null;
+  runtime?: {
+    manualId?: string;
+    userflowId?: string;
+    testID?: string;
+    nativeID?: string;
+    childText?: string;
+    accessibilityLabel?: string;
+    iconName?: string;
+    imageSrc?: string;
+    reactKey?: string;
+  };
+  parentInstanceId?: string;
+}
+
+const PRESSABLE_KINDS = new Set<string>([
+  'Pressable',
+  'TouchableOpacity',
+  'TouchableHighlight',
+  'TouchableWithoutFeedback',
+  'TouchableNativeFeedback',
+]);
+
+export function roleForKind(kind: string): SemanticRole {
+  if (PRESSABLE_KINDS.has(kind)) return 'Action';
+  if (kind === 'Text') return 'Text';
+  if (kind === 'Image') return 'Image';
+  if (kind === 'TextInput' || kind === 'TextField') return 'Input';
+  if (kind === 'View' || kind === 'ScrollView' || kind === 'SafeAreaView') return 'Group';
+  return 'Other';
+}
+
+let nextInstanceSeq = 1;
+
+function mintInstanceId(): string {
+  const id = `inst_${nextInstanceSeq.toString(36)}`;
+  nextInstanceSeq += 1;
+  return id;
+}
+
+/** Parent path for sibling grouping when `parentInstanceId` is unset (Babel stamps). */
+function siblingGroupKey(inst: AutoAnchorInstance): string {
+  const path = inst.templatePath || inst.structuralPath;
+  const idx = path.lastIndexOf(' > ');
+  return idx === -1 ? path : path.slice(0, idx);
+}
+
+export class AutoAnchorRegistry {
+  private readonly instances = new Map<string, AutoAnchorInstance>();
+  private readonly byRegistryKey = new Map<string, Set<string>>();
+  private readonly byManualId = new Map<string, Set<string>>();
+  private readonly byTemplatePath = new Map<string, Set<string>>();
+  private readonly listeners = new Set<AutoAnchorListener>();
+  private notifyScheduled = false;
+
+  registerInstance(input: RegisterInstanceInput): { instanceId: string; dispose: () => void } {
+    const instanceId = mintInstanceId();
+    const hints = input.hints ?? undefined;
+    const kind = input.kind;
+    const role = hints?.role ?? roleForKind(kind);
+    const templatePath = hints?.templatePath ?? hints?.ufid ?? input.registryKey;
+    const structuralPath = hints?.structuralPath ?? hints?.ufid ?? templatePath;
+    const runtime = input.runtime ?? {};
+
+    const manualId =
+      runtime.manualId ??
+      runtime.userflowId ??
+      hints?.literalUserflowId ??
+      runtime.testID ??
+      hints?.literalTestId ??
+      (runtime.nativeID && !runtime.nativeID.startsWith('uf_') ? runtime.nativeID : undefined);
+
+    const userflowId = runtime.userflowId ?? hints?.literalUserflowId;
+    const testID = runtime.testID ?? hints?.literalTestId;
+    const nativeID = runtime.nativeID ?? hints?.nativeId;
+    const childText = runtime.childText ?? hints?.childText;
+    const accessibilityLabel = runtime.accessibilityLabel ?? hints?.literalLabel;
+    const iconName = runtime.iconName ?? hints?.iconName;
+    const imageSrc = runtime.imageSrc ?? hints?.imageSrc;
+
+    const instance: AutoAnchorInstance = {
+      instanceId,
+      registryKey: input.registryKey,
+      ref: input.ref,
+      kind,
+      role,
+      isPressable: PRESSABLE_KINDS.has(kind),
+      templatePath,
+      structuralPath,
+      ...(input.instanceScope ? { instanceScope: input.instanceScope } : {}),
+      ...(manualId ? { manualId } : {}),
+      ...(userflowId ? { userflowId } : {}),
+      ...(testID ? { testID } : {}),
+      ...(nativeID ? { nativeID } : {}),
+      ...(childText ? { childText } : {}),
+      ...(accessibilityLabel ? { accessibilityLabel } : {}),
+      ...(hints?.childShape ? { childShape: hints.childShape } : {}),
+      ...(iconName ? { iconName } : {}),
+      ...(imageSrc ? { imageSrc } : {}),
+      ancestors: hints?.ancestors ? [...hints.ancestors] : [],
+      ...(hints?.ordinal !== undefined ? { ordinal: hints.ordinal } : {}),
+      ...(hints?.siblingIndex !== undefined ? { siblingIndex: hints.siblingIndex } : {}),
+      ...(input.parentInstanceId ? { parentInstanceId: input.parentInstanceId } : {}),
+      childInstanceIds: [],
+      ambiguous: false,
+    };
+
+    this.instances.set(instanceId, instance);
+    this.addIndex(this.byRegistryKey, input.registryKey, instanceId);
+    this.addIndex(this.byTemplatePath, templatePath, instanceId);
+    if (manualId) this.addIndex(this.byManualId, manualId, instanceId);
+    if (instance.userflowId) this.addIndex(this.byManualId, instance.userflowId, instanceId);
+    if (instance.testID) this.addIndex(this.byManualId, instance.testID, instanceId);
+
+    if (input.parentInstanceId) {
+      const parent = this.instances.get(input.parentInstanceId);
+      if (parent) parent.childInstanceIds.push(instanceId);
+    }
+
+    this.recomputeAmbiguity(input.registryKey, templatePath, manualId);
+    this.notify();
+
+    return {
+      instanceId,
+      dispose: () => {
+        this.unregisterInstance(instanceId);
+      },
+    };
+  }
+
+  updateInstance(
+    instanceId: string,
+    patch: Partial<
+      Pick<
+        AutoAnchorInstance,
+        | 'childText'
+        | 'accessibilityLabel'
+        | 'childShape'
+        | 'manualId'
+        | 'userflowId'
+        | 'testID'
+        | 'nativeID'
+        | 'instanceScope'
+        | 'structuralPath'
+        | 'ancestors'
+        | 'ordinal'
+        | 'siblingIndex'
+        | 'parentInstanceId'
+      >
+    >,
+  ): void {
+    const inst = this.instances.get(instanceId);
+    if (!inst) return;
+
+    const prevIds = {
+      manualId: inst.manualId,
+      userflowId: inst.userflowId,
+      testID: inst.testID,
+    };
+    Object.assign(inst, patch);
+    if (
+      patch.manualId !== undefined ||
+      patch.userflowId !== undefined ||
+      patch.testID !== undefined
+    ) {
+      const nextManual =
+        patch.manualId ??
+        inst.userflowId ??
+        inst.testID ??
+        (inst.nativeID && !inst.nativeID.startsWith('uf_') ? inst.nativeID : undefined);
+      if (nextManual) inst.manualId = nextManual;
+      else delete inst.manualId;
+    }
+    this.refreshManualIndexes(inst, prevIds);
+    this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
+    this.notify();
+  }
+
+  getInstance(instanceId: string): AutoAnchorInstance | undefined {
+    return this.instances.get(instanceId);
+  }
+
+  getInstancesByRegistryKey(key: string): AutoAnchorInstance[] {
+    return this.idsToInstances(this.byRegistryKey.get(key));
+  }
+
+  getInstancesByManualId(id: string): AutoAnchorInstance[] {
+    return this.idsToInstances(this.byManualId.get(id));
+  }
+
+  getInstancesByTemplatePath(path: string): AutoAnchorInstance[] {
+    return this.idsToInstances(this.byTemplatePath.get(path));
+  }
+
+  allInstances(): AutoAnchorInstance[] {
+    return Array.from(this.instances.values());
+  }
+
+  orderedSiblingsIncludingSelf(instanceId: string): AutoAnchorInstance[] {
+    const inst = this.instances.get(instanceId);
+    if (!inst) return [];
+    if (!inst.parentInstanceId) {
+      const group = siblingGroupKey(inst);
+      return this.allInstances()
+        .filter((i) => !i.parentInstanceId && siblingGroupKey(i) === group)
+        .sort((a, b) => (a.siblingIndex ?? 0) - (b.siblingIndex ?? 0));
+    }
+    const parent = this.instances.get(inst.parentInstanceId);
+    if (!parent) return [inst];
+    return parent.childInstanceIds
+      .map((id) => this.instances.get(id))
+      .filter((i): i is AutoAnchorInstance => !!i)
+      .sort((a, b) => (a.siblingIndex ?? 0) - (b.siblingIndex ?? 0));
+  }
+
+  siblingWindow(
+    instanceId: string,
+    windowSize = 2,
+  ): { previous: SiblingDescriptor[]; next: SiblingDescriptor[] } {
+    const ordered = this.orderedSiblingsIncludingSelf(instanceId);
+    const idx = ordered.findIndex((i) => i.instanceId === instanceId);
+    if (idx < 0) return { previous: [], next: [] };
+    const toDesc = (i: AutoAnchorInstance): SiblingDescriptor => ({
+      kind: i.kind,
+      role: i.role,
+      ...(i.childText ? { text: i.childText } : {}),
+      ...(i.testID ? { testID: i.testID } : {}),
+      ...(i.userflowId ? { userflowId: i.userflowId } : {}),
+    });
+    return {
+      previous: ordered.slice(Math.max(0, idx - windowSize), idx).map(toDesc),
+      next: ordered.slice(idx + 1, idx + 1 + windowSize).map(toDesc),
+    };
+  }
+
+  subscribe(listener: AutoAnchorListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  isAmbiguousKey(key: string): boolean {
+    const byKey = this.getInstancesByRegistryKey(key);
+    if (byKey.length > 0) return byKey.some((i) => i.ambiguous);
+    const byManual = this.getInstancesByManualId(key);
+    return byManual.length > 1 || byManual.some((i) => i.ambiguous);
+  }
+
+  /** Test helper — drop every instance and reset ids. */
+  clear(): void {
+    this.instances.clear();
+    this.byRegistryKey.clear();
+    this.byManualId.clear();
+    this.byTemplatePath.clear();
+    this.notifyScheduled = false;
+    nextInstanceSeq = 1;
+  }
+
+  private unregisterInstance(instanceId: string): void {
+    const inst = this.instances.get(instanceId);
+    if (!inst) return;
+
+    if (inst.parentInstanceId) {
+      const parent = this.instances.get(inst.parentInstanceId);
+      if (parent) {
+        parent.childInstanceIds = parent.childInstanceIds.filter((id) => id !== instanceId);
+      }
+    }
+    for (const childId of [...inst.childInstanceIds]) {
+      const child = this.instances.get(childId);
+      if (child) delete child.parentInstanceId;
+    }
+
+    this.instances.delete(instanceId);
+    this.removeIndex(this.byRegistryKey, inst.registryKey, instanceId);
+    this.removeIndex(this.byTemplatePath, inst.templatePath, instanceId);
+    if (inst.manualId) this.removeIndex(this.byManualId, inst.manualId, instanceId);
+    if (inst.userflowId) this.removeIndex(this.byManualId, inst.userflowId, instanceId);
+    if (inst.testID) this.removeIndex(this.byManualId, inst.testID, instanceId);
+
+    this.recomputeAmbiguity(inst.registryKey, inst.templatePath, inst.manualId);
+    this.notify();
+  }
+
+  private refreshManualIndexes(
+    inst: AutoAnchorInstance,
+    prev: {
+      manualId?: string | undefined;
+      userflowId?: string | undefined;
+      testID?: string | undefined;
+    },
+  ): void {
+    const prevKeys = new Set(
+      [prev.manualId, prev.userflowId, prev.testID].filter((k): k is string => !!k),
+    );
+    const nextKeys = new Set(
+      [inst.manualId, inst.userflowId, inst.testID].filter((k): k is string => !!k),
+    );
+    for (const key of prevKeys) {
+      if (!nextKeys.has(key)) this.removeIndex(this.byManualId, key, inst.instanceId);
+    }
+    for (const key of nextKeys) {
+      if (!prevKeys.has(key)) this.addIndex(this.byManualId, key, inst.instanceId);
+    }
+  }
+
+  private recomputeAmbiguity(registryKey: string, templatePath: string, manualId?: string): void {
+    const mark = (list: AutoAnchorInstance[]) => {
+      const ambiguous = list.length > 1 && list.every((i) => !i.manualId);
+      for (const i of list) {
+        i.ambiguous =
+          ambiguous || (i.manualId ? this.getInstancesByManualId(i.manualId).length > 1 : false);
+      }
+    };
+    mark(this.getInstancesByRegistryKey(registryKey));
+    mark(this.getInstancesByTemplatePath(templatePath));
+    if (manualId) {
+      const list = this.getInstancesByManualId(manualId);
+      for (const i of list) i.ambiguous = list.length > 1;
+    }
+  }
+
+  private addIndex(map: Map<string, Set<string>>, key: string, instanceId: string): void {
+    let set = map.get(key);
+    if (!set) {
+      set = new Set();
+      map.set(key, set);
+    }
+    set.add(instanceId);
+  }
+
+  private removeIndex(map: Map<string, Set<string>>, key: string, instanceId: string): void {
+    const set = map.get(key);
+    if (!set) return;
+    set.delete(instanceId);
+    if (set.size === 0) map.delete(key);
+  }
+
+  private idsToInstances(set: Set<string> | undefined): AutoAnchorInstance[] {
+    if (!set) return [];
+    const out: AutoAnchorInstance[] = [];
+    for (const id of set) {
+      const inst = this.instances.get(id);
+      if (inst) out.push(inst);
+    }
+    return out;
+  }
+
+  private notify(): void {
+    if (this.notifyScheduled) return;
+    this.notifyScheduled = true;
+    const flush = () => {
+      this.notifyScheduled = false;
+      for (const l of this.listeners) {
+        try {
+          l();
+        } catch {
+          // listeners are infrastructure; never propagate
+        }
+      }
+    };
+    if (typeof queueMicrotask === 'function') {
+      queueMicrotask(flush);
+    } else {
+      void Promise.resolve().then(flush);
+    }
+  }
+}
+
+export const autoAnchorRegistry = new AutoAnchorRegistry();

package/src/anchors/ScrollContainerRegistry.ts

@@ -0,0 +1,108 @@
+import type { NativeScrollEvent, NativeSyntheticEvent, ScrollView, View } from 'react-native';
+
+import type { Rect } from '../surfaces/tooltip/inferTooltipPlacement';
+
+/** Padding applied when scrolling a target into the visible region of a container. */
+const INTO_VIEW_PADDING = 24;
+
+export interface ScrollContainerHost {
+  measureInWindow: (
+    callback: (x: number, y: number, width: number, height: number) => void,
+  ) => void;
+  getContentOffset: () => { x: number; y: number };
+  scrollTo: (options: { x?: number; y?: number; animated?: boolean }) => void;
+}
+
+type Listener = () => void;
+
+/**
+ * Registry of host {@link ScrollView}s used as an explicit override when
+ * scrolling tooltip anchors into view. Prefer automatic fiber discovery for
+ * `testID` anchors; register here for scroll libraries the walk cannot drive.
+ */
+export class ScrollContainerRegistry {
+  private readonly containers = new Set<ScrollContainerHost>();
+  private readonly listeners = new Set<Listener>();
+
+  register(host: ScrollContainerHost): void {
+    this.containers.add(host);
+    this.emit();
+  }
+
+  unregister(host: ScrollContainerHost): void {
+    this.containers.delete(host);
+    this.emit();
+  }
+
+  /** Snapshot of registered containers (most recently registered last). */
+  list(): ScrollContainerHost[] {
+    return [...this.containers];
+  }
+
+  /**
+   * Scroll the first registered container that can bring `target` into its
+   * visible window region. Best-effort — no-op when nothing is registered.
+   */
+  scrollTargetIntoView(target: Rect): void {
+    for (const host of this.containers) {
+      host.measureInWindow((x, y, width, height) => {
+        if (width <= 0 || height <= 0) return;
+
+        const offset = host.getContentOffset();
+        const targetContentY = offset.y + (target.y - y);
+        let nextY: number | null = null;
+
+        if (target.y < y + INTO_VIEW_PADDING) {
+          nextY = Math.max(0, targetContentY - INTO_VIEW_PADDING);
+        } else if (target.y + target.height > y + height - INTO_VIEW_PADDING) {
+          nextY = Math.max(0, targetContentY + target.height - height + INTO_VIEW_PADDING);
+        }
+
+        if (nextY == null || Math.abs(nextY - offset.y) < 1) return;
+        host.scrollTo({ y: nextY, animated: true });
+      });
+      // Prefer the first container for MVP; hosts typically have one root ScrollView.
+      return;
+    }
+  }
+
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  clear(): void {
+    this.containers.clear();
+    this.emit();
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+/** Module singleton used by {@link useUserflowScrollContainer} and TooltipSurface. */
+export const scrollContainerRegistry = new ScrollContainerRegistry();
+
+/** Build a host from a live ScrollView + tracked content offset. */
+export function createScrollContainerHost(
+  node: ScrollView,
+  getContentOffset: () => { x: number; y: number },
+): ScrollContainerHost {
+  const measurable = node as ScrollView & View;
+  return {
+    measureInWindow: (callback) => {
+      measurable.measureInWindow(callback);
+    },
+    getContentOffset,
+    scrollTo: (options) => {
+      node.scrollTo(options);
+    },
+  };
+}
+
+export type ScrollContainerScrollHandler = (event: NativeSyntheticEvent<NativeScrollEvent>) => void;

package/src/anchors/anchorChangeTicker.ts

@@ -0,0 +1,84 @@
+import { anchorRegistry } from './AnchorRegistry';
+import { fiberScanRoot } from './fiber/FiberScanRoot';
+
+type Listener = () => void;
+
+/**
+ * Change signal for ELEMENT client conditions.
+ *
+ * Fiber-resolved anchors (testID / nativeID / accessibilityLabel) do not emit
+ * registry events, so we combine:
+ * - {@link anchorRegistry} mount/unmount
+ * - {@link fiberScanRoot} mount/unmount
+ * - screen-change notifications
+ * - a slow interval that only runs while at least one listener is subscribed
+ */
+class AnchorChangeTicker {
+  private readonly listeners = new Set<Listener>();
+  private intervalHandle: ReturnType<typeof setInterval> | null = null;
+  private unsubRegistry: (() => void) | null = null;
+  private unsubScan: (() => void) | null = null;
+
+  /** Poll interval while ELEMENT conditions are tracked (ms). */
+  static readonly INTERVAL_MS = 1000;
+
+  subscribe(listener: Listener): () => void {
+    const wasEmpty = this.listeners.size === 0;
+    this.listeners.add(listener);
+    if (wasEmpty) {
+      this.start();
+    }
+    return () => {
+      this.listeners.delete(listener);
+      if (this.listeners.size === 0) {
+        this.stop();
+      }
+    };
+  }
+
+  /** Push a change from outside (e.g. screen navigation). */
+  notify(): void {
+    this.emit();
+  }
+
+  /** Test helper. */
+  resetForTests(): void {
+    this.stop();
+    this.listeners.clear();
+  }
+
+  private start(): void {
+    if (!this.unsubRegistry) {
+      this.unsubRegistry = anchorRegistry.subscribe(() => this.emit());
+    }
+    if (!this.unsubScan) {
+      this.unsubScan = fiberScanRoot.subscribe(() => this.emit());
+    }
+    if (!this.intervalHandle) {
+      this.intervalHandle = setInterval(() => this.emit(), AnchorChangeTicker.INTERVAL_MS);
+    }
+  }
+
+  private stop(): void {
+    if (this.intervalHandle) {
+      clearInterval(this.intervalHandle);
+      this.intervalHandle = null;
+    }
+    if (this.unsubRegistry) {
+      this.unsubRegistry();
+      this.unsubRegistry = null;
+    }
+    if (this.unsubScan) {
+      this.unsubScan();
+      this.unsubScan = null;
+    }
+  }
+
+  private emit(): void {
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+}
+
+export const anchorChangeTicker = new AnchorChangeTicker();