@scalebun-release/react-native 2.5.0

package/lib/commonjs/features/journey/touchTarget.js

@@ -0,0 +1,249 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.describeTouchTarget = describeTouchTarget;
+exports.resolveTouchTarget = resolveTouchTarget;
+exports.targetIdentity = targetIdentity;
+/**
+ * Resolve WHAT was tapped, from a React Native touch event.
+ *
+ * THE GAP THIS CLOSES. Native taps carried coordinates, a gesture type and a screen — but no identity
+ * for the thing touched. Every tap in the app therefore arrived as `gesture:tap`, so the Events explorer
+ * showed one undifferentiated row per gesture type no matter how many different buttons users pressed.
+ * Web has had element text since day one; mobile had nothing to group by.
+ *
+ * WHY THE FIBER. There is no DOM. The only place a tapped view's identity exists in JS is the React
+ * fiber hanging off the touch event (`_targetInst`), which carries `memoizedProps` — where
+ * `accessibilityLabel` and `testID` live. This is a React internal, so every access is defensive and
+ * the whole thing degrades to `null` rather than throwing: an analytics label is never worth a crash.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
+ * RN-2 — THE IDENTITY LADDER USED TO CAPTURE USER TEXT, AND THAT IS A PRIVACY DEFECT, NOT A
+ * TRADE-OFF.
+ *
+ * The previous preference order was:
+ *
+ *   1. accessibilityLabel   2. testID   3. a literal string child   4. nearest component
+ *
+ * Ranks 1 and 3 are FREE TEXT authored for humans, and in a real app they routinely contain user
+ * data. An accessible order row is labelled "Order 1042 for mohamed@scalebun.com". A pay button
+ * reads "Pay EGP 1,442". A contact row's caption is a person's name. Rank 1 was preferred over
+ * `testID`, so the leakiest source won whenever it existed.
+ *
+ * Two separate harms, and the second is easy to miss:
+ *
+ *   PRIVACY. `describeTouchTarget`'s output is persisted as the interaction's `target`. So names,
+ *   email addresses and amounts were being written into an analytics store, under a field nobody
+ *   would think to audit for PII. The same product already found 27 rows in `replay_events`
+ *   carrying email addresses through a different route; this was a second one.
+ *
+ *   CORRECTNESS. `target` is an AGGREGATION KEY. Keyed on text that varies per user, a single
+ *   button produces one bucket per person — so the grouping this feature exists to provide is
+ *   destroyed precisely in the screens that matter most. A leaky key is also a useless key.
+ *
+ * SO THE LADDER IS NOW DERIVED FROM CODE, NEVER FROM CONTENT:
+ *
+ *   1. `testID`     — authored to identify, stable across copy edits, and by convention never
+ *                     user data. The strongest signal and now the first.
+ *   2. `path`       — the component-name chain from the tapped node upward, e.g.
+ *                     `CartScreen>OrderRow>Pressable`. Structural: it changes when the code
+ *                     changes, not when the data does. This is what makes the ladder useful in
+ *                     the overwhelming majority of apps, which have no testIDs — without it,
+ *                     removing free text would have meant removing identity.
+ *   3. `component`  — the nearest named component alone. Coarse, but a code identifier.
+ *
+ * Free text is still RESOLVABLE, because a team that has audited its own labels may legitimately
+ * want them, but it is opt-in per call (`includeText`) and it is NEVER what
+ * `describeTouchTarget` returns. Default-off matters more than the option: a default that leaks
+ * is a leak, whatever the documentation says.
+ *
+ * WHY THIS SHIPS WITH RN-1 (persistence) RATHER THAN AFTER IT. RN-1 makes the resolved target
+ * actually reach the backend. Landing that first would persist the leaky ladder and create a
+ * historical PII problem to clean up; landing the sanitised ladder first and persistence second
+ * leaves a window where the feature looks broken. They are one change.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────
+ */
+
+/** Where a resolved identity came from — so a consumer can tell an authored id from a guess. */
+
+/** How far up the tree to look before giving up. Deep enough for a wrapped button, cheap enough to run on every tap. */
+const MAX_DEPTH = 12;
+/** Labels longer than this are truncated — a caption, not a paragraph. */
+const MAX_LEN = 60;
+/**
+ * How many component names the structural path may hold.
+ *
+ * Four is enough to separate two same-named controls in different containers
+ * (`Pressable<OrderRow<CartScreen` vs `Pressable<SuggestionRow<CartScreen`) without letting the
+ * key drift every time someone adds a wrapper view higher up. A path that changes on unrelated
+ * refactors is a key that silently splits its own history.
+ */
+const MAX_PATH_SEGMENTS = 4;
+function str(v) {
+  if (typeof v !== 'string') return undefined;
+  const s = v.trim();
+  return s ? s.slice(0, MAX_LEN) : undefined;
+}
+
+/** Display name of a component fiber; host components ('View', 'RCTText') are skipped as meaningless. */
+function componentName(f) {
+  const t = f.elementType ?? f.type;
+  if (!t) return undefined;
+  // A string type is a HOST component (View/Text/RCTView) — it names the primitive, not the control.
+  if (typeof t === 'string') return undefined;
+  const n = t.displayName || t.name;
+  if (!n || typeof n !== 'string') return undefined;
+  // Anonymous / internal wrappers carry no meaning for a human reading an event list.
+  if (n.length < 2 || n.startsWith('_') || n === 'Unknown') return undefined;
+  return n.slice(0, MAX_LEN);
+}
+
+/** First literal string child, e.g. <Text>Buy now</Text>. FREE TEXT — see the header. */
+function textChild(props) {
+  if (!props) return undefined;
+  const c = props.children;
+  if (typeof c === 'string') return str(c);
+  if (Array.isArray(c)) {
+    for (const item of c) {
+      const s = str(item);
+      if (s) return s;
+    }
+  }
+  return undefined;
+}
+
+/** The fiber for a touch event, across the shapes RN has used. Never throws. */
+function fiberOf(event) {
+  if (!event || typeof event !== 'object') return null;
+  const e = event;
+  const direct = e._targetInst;
+  if (direct && typeof direct === 'object') return direct;
+  const target = e.target ?? e.nativeEvent?.target;
+  if (target) {
+    const handle = target._internalInstanceHandle ?? target._targetInst;
+    if (handle && typeof handle === 'object') return handle;
+  }
+  return null;
+}
+
+/**
+ * Walk up from the touched fiber collecting the best identity available.
+ *
+ * Keeps walking after a hit so a wrapper's `testID` can still be picked up when the leaf had none,
+ * and stops as soon as a `testID` is known AND the path is full — nothing above can improve on that.
+ */
+function resolveTouchTarget(event, optsOrMaxDepth = {}) {
+  /* Number form kept for the previous signature `resolveTouchTarget(event, maxDepth)`. */
+  const opts = typeof optsOrMaxDepth === 'number' ? {
+    maxDepth: optsOrMaxDepth
+  } : optsOrMaxDepth;
+  const maxDepth = opts.maxDepth ?? MAX_DEPTH;
+  let f = fiberOf(event);
+  if (!f) return null;
+  const out = {};
+  const segments = [];
+  const ancestors = [];
+  let depth = 0;
+  try {
+    while (f && depth < maxDepth) {
+      const props = f.memoizedProps;
+      if (props) {
+        const beforeTestId = out.testID;
+        out.testID ??= str(props.testID);
+        /* The node is pinned to the fiber that supplied the testID — the CONTROL, not the
+           deepest node hit. A Text inside a Pressable is a tap on the Pressable, so the rect
+           has to be the Pressable's or the containment test would be run against the caption. */
+        if (!beforeTestId && out.testID) out.node = f.stateNode;
+        /* The nearest enclosing cell wins: nested lists mean a row can sit inside another
+           row, and the innermost is the one the finger is actually in. `??=` keeps the first
+           seen while walking outward, which is the innermost. */
+        if (typeof props.cellKey === 'string' && props.cellKey) {
+          out.itemKey ??= str(props.cellKey);
+          if (typeof props.index === 'number' && Number.isFinite(props.index)) {
+            out.itemIndex ??= props.index;
+          }
+        }
+        if (opts.includeText) {
+          out.accessibilityLabel ??= str(props.accessibilityLabel);
+          out.text ??= textChild(props);
+        }
+      }
+      /* Host instances only — a composite fiber has no native tag, so keeping them would pad
+         the chain with entries no scroller could ever match. */
+      if (f.stateNode) ancestors.push(f.stateNode);
+      const name = componentName(f);
+      if (name) {
+        out.component ??= name;
+        /* Consecutive duplicates collapse: a component that renders itself through a memo or a
+           forwardRef appears twice in the fiber chain and would otherwise pad the path with a
+           repetition that carries no information. */
+        if (segments[segments.length - 1] !== name && segments.length < MAX_PATH_SEGMENTS) {
+          segments.push(name);
+        }
+      }
+      if (out.testID && segments.length >= MAX_PATH_SEGMENTS) break;
+      f = f.return ?? null;
+      depth++;
+    }
+  } catch {
+    /* React internals shifted under us — return whatever was gathered so far */
+  }
+
+  /* Tapped node first, so the most specific segment leads and a truncated path is still anchored
+     to the thing actually touched. */
+  if (segments.length) out.path = segments.join('<');
+
+  /* No authored testID anywhere, so identity came from the structural path. Anchor the rect to
+     the node that was actually touched — imperfect (it may be the caption rather than the
+     control) but honest, and better than no geometry for the majority of apps, which author no
+     testIDs. `targetSource` records which case this was, so a consumer can weight it. */
+  if (!out.node) out.node = fiberOf(event)?.stateNode;
+  if (ancestors.length) out.ancestors = ancestors;
+  return out.testID || out.path || out.component || out.accessibilityLabel || out.text || out.itemKey ? out : null;
+}
+
+/**
+ * One short, STABLE, non-identifying label for the tapped thing.
+ *
+ * This is what ends up grouping the Events explorer and what gets persisted as the interaction's
+ * target, so it must satisfy two constraints at once: stable across copy edits, and free of user
+ * data. Both rule out visible text, which is why the free-text fields are not consulted here even
+ * when they have been resolved — see the RN-2 note in the header.
+ */
+function describeTouchTarget(t) {
+  if (!t) return undefined;
+  return t.testID || t.path || t.component;
+}
+
+/**
+ * The identity plus WHERE IT CAME FROM.
+ *
+ * A consumer cannot treat an authored `testID` and a structural `path` as equally trustworthy: the
+ * first is a promise from the app's authors that this control is this control, the second is an
+ * inference that breaks when the tree is refactored. Returning the source lets the accounting lane
+ * say WHY a tap could not be attributed, instead of reporting a missing target and leaving the
+ * reader to guess whether the control had no identity or the walk failed.
+ */
+function targetIdentity(t) {
+  if (!t) return {
+    source: 'none'
+  };
+  if (t.testID) return {
+    id: t.testID,
+    source: 'testID'
+  };
+  if (t.path) return {
+    id: t.path,
+    source: 'path'
+  };
+  if (t.component) return {
+    id: t.component,
+    source: 'component'
+  };
+  return {
+    source: 'none'
+  };
+}
+//# sourceMappingURL=touchTarget.js.map

package/lib/commonjs/features/journey/uiState.js

@@ -0,0 +1,188 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.clearUiState = clearUiState;
+exports.onUiStateChange = onUiStateChange;
+exports.resetUiStateListeners = resetUiStateListeners;
+exports.setUiState = setUiState;
+exports.uiStateInstrumented = uiStateInstrumented;
+exports.uiStateListenerCount = uiStateListenerCount;
+exports.uiStateSignature = uiStateSignature;
+/**
+ * UI STATE AT INTERACTION TIME — React Native.
+ *
+ * A screen is not just `Cart`. It is `Cart` with the filter sheet down, or up; with the address form
+ * expanded, or collapsed. Those are different interaction surfaces and a tap on one must never be
+ * counted on another — heat from the open sheet painted over the closed layout is a picture of
+ * something that never existed.
+ *
+ * HOW THIS DIFFERS FROM THE WEB, and the difference is not an omission:
+ *
+ *   The web SDK ALSO detects state automatically, by reading `aria-expanded` and open `<dialog>`
+ *   elements out of the live DOM. Those are platform-defined, so reading them is a measurement.
+ *
+ *   React Native has no equivalent. There is no queryable tree of accessibility state that says a
+ *   bottom sheet is up; a sheet is a component with a boolean in someone's store, and the only place
+ *   that boolean exists is the host's own code. Guessing at it — from a modal's presence in the tree, or
+ *   from a component name — would produce a state key that is right on some apps and silently wrong on
+ *   others, and a wrong state key partitions taps into buckets corresponding to nothing.
+ *
+ * So on RN, state is DECLARED and never inferred. `ScaleBun.setUiState('filter-sheet', 'open')` is the
+ * whole mechanism, and its absence means "not captured" rather than "nothing was open". That
+ * distinction is carried all the way to the dashboard: a tap with no declared state is NULL, not '',
+ * and cannot be selected as a state or counted as one. Reporting it as "nothing was open" would be
+ * asserting a measurement nobody took.
+ *
+ * PAIRED WITH: whatzbug-web-sdk/packages/web/src/features/journey/uiState.ts — same wire format
+ * (`name:value` pairs, sorted, `;`-joined, <= 96 chars), same separator stripping, same explicit-wins
+ * precedence, so one dashboard control queries both platforms.
+ */
+
+/** Host-declared state dimensions. The only source on this platform. */
+const declared = new Map();
+
+/**
+ * Whether the host has used the state API at all this process. Lets a tap with nothing declared say
+ * "this app instruments state, and nothing is declared right now" (captured_empty) instead of "this
+ * app never told us anything" (not_instrumented). Neither is a CLOSED state: the signature stays
+ * undefined in both, so nothing downstream files the tap under "closed".
+ */
+let instrumented = false;
+function uiStateInstrumented() {
+  return instrumented;
+}
+
+/**
+ * `;` and `:` are the wire separators and cannot appear inside a name or value; the length is bounded.
+ *
+ * Names and values are IDENTIFIERS, not content. They become aggregation keys in the dashboard, so a
+ * value carrying a person's name or a cart total would put user data into a query key — and into every
+ * chart legend built from it.
+ */
+const clean = s => typeof s === 'string' ? s.replace(/[;:|]/g, '').trim().slice(0, 32) : '';
+
+/**
+ * Declare the state of one UI dimension.
+ *
+ * Call it when the state CHANGES, not on every render: the value is read at interaction time, so it
+ * only has to be correct by the time the next tap lands.
+ */
+function setUiState(name, value) {
+  const n = clean(name);
+  const v = clean(value);
+  if (!n || !v) return;
+  instrumented = true;
+  if (declared.get(n) === v) return;
+  declared.set(n, v);
+  notifyChanged();
+}
+
+/**
+ * Stop reporting a dimension — or, with no name, all of them.
+ *
+ * Later taps carry no value for it, which is not the same as carrying a value. Clearing all is what a
+ * screen unmount wants: declarations from the previous screen would otherwise follow the user onto a
+ * surface where they mean nothing, and every tap there would be filed under a state that was not on
+ * screen.
+ */
+function clearUiState(name) {
+  instrumented = true;
+  const before = declared.size;
+  if (name === undefined) declared.clear();else declared.delete(clean(name));
+  if (declared.size !== before) notifyChanged();
+}
+
+/**
+ * The signature for the interaction happening RIGHT NOW, or undefined when nothing is declared.
+ *
+ * undefined rather than '' deliberately — see the header. '' is the web's "we looked and nothing was
+ * open"; on RN there is nothing to look at, so the honest answer is silence.
+ */
+function uiStateSignature() {
+  if (!declared.size) return undefined;
+  /* SORTED, or the same surface produces different signatures depending on the order the host happened
+     to declare things in, and every count fragments into several that mean nothing. */
+  const pairs = [...declared.keys()].sort().map(k => `${k}:${declared.get(k)}`);
+  let signature = '';
+  for (const pair of pairs) {
+    const next = signature ? `${signature};${pair}` : pair;
+    if (next.length > 96) break;
+    signature = next;
+  }
+  return signature || undefined;
+}
+
+/**
+ * RN-11 — TELL SOMEONE THE STATE CHANGED, so a frame can exist for it.
+ *
+ * THE GAP. Declaring a state used to mutate a Map and nothing else. Nothing captured a frame, so
+ * the visual for a declared state existed only if a screenshot happened to be taken for some other
+ * reason — a navigation, a timer, or the interaction capture that fires AFTER the touch and
+ * photographs the outcome. A state could therefore be recorded as a fact with no picture of it
+ * anywhere, or with a picture of the state that replaced it.
+ *
+ * The native capture reasons are NAVIGATION, MANUAL, INTERACTION and TIMER. None of them is "the
+ * UI changed shape", which is exactly the moment a heatmap needs a frame.
+ *
+ * FIRING ON A REAL CHANGE ONLY, AND WHY THAT IS THE SDK'S JOB. The advice above says to call
+ * `setUiState` when the state changes rather than on every render — but that is advice to the
+ * host, not a guarantee. A component that declares its state inside render is ordinary React, and
+ * trusting the caller would mean a screenshot per render: a performance disaster in exactly the
+ * apps that instrument most carefully. So a redundant set — same dimension, same value — is now a
+ * no-op, and the change test lives here where it cannot be got wrong by a host.
+ *
+ * COALESCED, because a transition usually declares several dimensions in one tick ("drawer:open"
+ * and "overlay:visible" belong to one visual change). Notifying per call would capture the
+ * intermediate shapes, which are states the user never saw.
+ *
+ * The listener is deliberately NOT given the signature. A subscriber that wants it calls
+ * `uiStateSignature()` at the moment it acts, which is the value that will actually be attached
+ * to the next tap; handing over a snapshot invites acting on a state that has already moved on.
+ */
+
+const listeners = new Set();
+let pending = null;
+
+/**
+ * Subscribe to declared-state changes. Returns an unsubscribe.
+ *
+ * Registration is idempotent per function reference, so a component that re-subscribes on every
+ * render does not accumulate listeners — a leak that would only show up in long sessions.
+ */
+function onUiStateChange(listener) {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+}
+
+/** Drop every listener and any pending notification. For teardown between sessions. */
+function resetUiStateListeners() {
+  listeners.clear();
+  if (pending !== null) {
+    clearTimeout(pending);
+    pending = null;
+  }
+}
+
+/** For assertions that a re-subscribing caller has not leaked. */
+function uiStateListenerCount() {
+  return listeners.size;
+}
+function notifyChanged() {
+  if (pending !== null) return;
+  pending = setTimeout(() => {
+    pending = null;
+    for (const listener of listeners) {
+      try {
+        listener();
+      } catch {
+        /* One bad subscriber must not stop the others, and must never surface to the host: a
+           screenshot is not worth an app crash. */
+      }
+    }
+  }, 0);
+}
+//# sourceMappingURL=uiState.js.map