@appsent-co/react-native-watchos 0.1.0

package/src/modifiers/toolbarItems.ts

@@ -0,0 +1,23 @@
+import type { ReactNode } from 'react';
+import { createModifier } from './createModifier';
+
+export interface ToolbarParams {
+  /// The toolbar items. On watchOS, placement is limited — items are
+  /// supplied without explicit `ToolbarItemPlacement` and the system
+  /// positions them (typically in the top bar of a `<NavigationStack>`).
+  content: ReactNode;
+}
+
+/// SwiftUI `.toolbar { content }`. Adds toolbar items to a view inside a
+/// `<NavigationStack>`.
+///
+/// LIMITATION: watchOS exposes only a narrow set of toolbar placements, so
+/// this binding keeps it simple — `content` is rendered as the toolbar
+/// body and the system chooses placement. Per-item placement control is
+/// not exposed. (This file is named `toolbarItems.ts` because the
+/// `toolbar.ts` filename is owned by a separate "Toolbar polish" unit; the
+/// exported factory and `$type` are still `toolbar`.)
+export function toolbar(params: ToolbarParams) {
+  const { content } = params;
+  return createModifier('toolbar', { content });
+}

package/src/modifiers/toolbarTitleDisplayMode.ts

@@ -0,0 +1,26 @@
+import { createModifier } from './createModifier';
+
+/// SwiftUI `ToolbarTitleDisplayMode` values.
+export type ToolbarTitleDisplayModeValue = 'automatic' | 'inline' | 'large';
+
+export interface ToolbarTitleDisplayModeParams {
+  /// `'automatic'` | `'inline'` | `'large'`.
+  mode: ToolbarTitleDisplayModeValue;
+}
+
+/// SwiftUI `.toolbarTitleDisplayMode(_:)` (watchOS 10+). Controls how the
+/// navigation title is displayed. No-op on watchOS 9.
+export function toolbarTitleDisplayMode(
+  mode: ToolbarTitleDisplayModeValue
+): ReturnType<typeof createModifier>;
+export function toolbarTitleDisplayMode(
+  params: ToolbarTitleDisplayModeParams
+): ReturnType<typeof createModifier>;
+export function toolbarTitleDisplayMode(
+  a: ToolbarTitleDisplayModeParams | ToolbarTitleDisplayModeValue
+) {
+  if (typeof a === 'string') {
+    return createModifier('toolbarTitleDisplayMode', { mode: a });
+  }
+  return createModifier('toolbarTitleDisplayMode', a);
+}

package/src/modifiers/toolbarTitleMenu.ts

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { createModifier } from './createModifier';
+
+export interface ToolbarTitleMenuParams {
+  /// The menu's content — typically `Button`s — shown when the user taps the
+  /// navigation title.
+  content: ReactNode;
+}
+
+/// SwiftUI `.toolbarTitleMenu { … }` (watchOS 9+). Populates the menu that
+/// appears from the navigation title.
+export function toolbarTitleMenu(content: ReactNode): ReturnType<typeof createModifier>;
+export function toolbarTitleMenu(
+  params: ToolbarTitleMenuParams
+): ReturnType<typeof createModifier>;
+export function toolbarTitleMenu(a: ToolbarTitleMenuParams | ReactNode) {
+  if (a && typeof a === 'object' && 'content' in a) {
+    return createModifier('toolbarTitleMenu', a as ToolbarTitleMenuParams);
+  }
+  return createModifier('toolbarTitleMenu', { content: a as ReactNode });
+}

package/src/modifiers/toolbarVisibility.ts

@@ -0,0 +1,31 @@
+import { createModifier } from './createModifier';
+import type { ToolbarBars } from './toolbarBackground';
+
+/// SwiftUI `Visibility` values.
+export type ToolbarVisibilityValue = 'automatic' | 'visible' | 'hidden';
+
+export interface ToolbarVisibilityParams {
+  /// `'automatic'` | `'visible'` | `'hidden'`.
+  visibility: ToolbarVisibilityValue;
+  /// Which bar(s) to affect. Defaults to `'automatic'`.
+  bars?: ToolbarBars;
+}
+
+/// SwiftUI `.toolbarVisibility(_:for:)` on newer OSes, falling back to the
+/// watchOS-9 `.toolbar(_ Visibility, for:)`. Shows or hides the bar(s).
+export function toolbarVisibility(
+  visibility: ToolbarVisibilityValue,
+  bars?: ToolbarBars
+): ReturnType<typeof createModifier>;
+export function toolbarVisibility(
+  params: ToolbarVisibilityParams
+): ReturnType<typeof createModifier>;
+export function toolbarVisibility(
+  a: ToolbarVisibilityParams | ToolbarVisibilityValue,
+  bars?: ToolbarBars
+) {
+  if (typeof a === 'string') {
+    return createModifier('toolbarVisibility', { visibility: a, bars });
+  }
+  return createModifier('toolbarVisibility', a);
+}

package/src/modifiers/tracking.ts

@@ -0,0 +1,9 @@
+import { createModifier } from './createModifier';
+
+/// SwiftUI `.tracking(_:)`. Sets the tracking, in points, between each
+/// character pair. Like `kerning` but it also adds the spacing after the
+/// final character. Tracking takes precedence over `kerning` when both
+/// are applied.
+export function tracking(value: number) {
+  return createModifier('tracking', { value });
+}

package/src/modifiers/transformEffect.ts

@@ -0,0 +1,31 @@
+import { createModifier } from './createModifier';
+
+/// The six components of a 2D affine transform matrix, matching
+/// `CGAffineTransform(a:b:c:d:tx:ty:)`:
+/// ```
+/// | a  b  0 |
+/// | c  d  0 |
+/// | tx ty 1 |
+/// ```
+export interface AffineTransformParams {
+  /// Horizontal scale (m11). Defaults to `1`.
+  a?: number;
+  /// Vertical shear (m12). Defaults to `0`.
+  b?: number;
+  /// Horizontal shear (m21). Defaults to `0`.
+  c?: number;
+  /// Vertical scale (m22). Defaults to `1`.
+  d?: number;
+  /// Horizontal translation. Defaults to `0`.
+  tx?: number;
+  /// Vertical translation. Defaults to `0`.
+  ty?: number;
+}
+
+/// SwiftUI `.transformEffect(_:)`. Applies an arbitrary 2D affine
+/// transform built from `CGAffineTransform(a:b:c:d:tx:ty:)` to the
+/// view's rendered output. Omitted components default to the identity
+/// matrix (`a = d = 1`, others `0`).
+export function transformEffect(params: AffineTransformParams) {
+  return createModifier('transformEffect', params);
+}

package/src/modifiers/transforms.ts

@@ -0,0 +1,17 @@
+// "Transforms" modifiers — geometric effects on a view's rendered output
+// (rotation, 3D rotation, scale, affine + projection transforms).
+export {
+  rotationEffect,
+  type RotationEffectParams,
+  type TransformAnchor,
+} from './rotationEffect';
+export {
+  rotation3DEffect,
+  type Rotation3DEffectParams,
+} from './rotation3DEffect';
+export { scaleEffect, type ScaleEffectParams } from './scaleEffect';
+export {
+  transformEffect,
+  type AffineTransformParams,
+} from './transformEffect';
+export { projectionEffect } from './projectionEffect';

package/src/modifiers/transition.ts

@@ -0,0 +1,35 @@
+import { createModifier } from './createModifier';
+
+export type TransitionType =
+  | 'opacity'
+  | 'slide'
+  | 'scale'
+  | 'identity'
+  | 'move';
+
+export type TransitionEdge = 'top' | 'bottom' | 'leading' | 'trailing';
+
+export interface TransitionParams {
+  /// The transition preset. Defaults to `'opacity'`.
+  type?: TransitionType;
+  /// Edge to move from/to. Only honored when `type` is `'move'`
+  /// (defaults to `'bottom'`).
+  edge?: TransitionEdge;
+}
+
+/// SwiftUI `.transition(_:)`. Describes how the view animates in/out when it
+/// is inserted into or removed from the view tree (pair with `animation`).
+///
+/// ```tsx
+/// <Text modifiers={[transition({ type: 'move', edge: 'leading' })]} />
+/// ```
+export function transition(
+  type?: TransitionType
+): ReturnType<typeof createModifier>;
+export function transition(
+  params: TransitionParams
+): ReturnType<typeof createModifier>;
+export function transition(a: TransitionType | TransitionParams = 'opacity') {
+  if (typeof a === 'string') return createModifier('transition', { type: a });
+  return createModifier('transition', a);
+}

package/src/modifiers/truncationMode.ts

@@ -0,0 +1,18 @@
+import { createModifier } from './createModifier';
+
+/// SwiftUI `Text.TruncationMode` values — where the ellipsis appears when
+/// text is truncated.
+export type TruncationMode = 'head' | 'middle' | 'tail';
+
+export interface TruncationModeParams {
+  mode?: TruncationMode;
+}
+
+/// SwiftUI `.truncationMode(_:)`. Controls where text within the view is
+/// truncated when it doesn't fit. Pass a mode string directly or an object.
+export function truncationMode(params?: TruncationModeParams | TruncationMode) {
+  if (typeof params === 'string') {
+    return createModifier('truncationMode', { mode: params });
+  }
+  return createModifier('truncationMode', params);
+}

package/src/modifiers/underline.ts

@@ -0,0 +1,18 @@
+import { createModifier } from './createModifier';
+
+export interface UnderlineParams {
+  /// Whether the underline is active. Defaults to `true`.
+  value?: boolean;
+  /// Underline color. Accepts a named color or hex (`'#RRGGBB'` /
+  /// `'#RRGGBBAA'`). Omit to use the text's foreground color.
+  color?: string;
+}
+
+/// SwiftUI `.underline(_:color:)`. Applies an underline to text within the
+/// view. Pass a boolean to toggle it, or an object to also set a color.
+export function underline(params?: UnderlineParams | boolean) {
+  if (typeof params === 'boolean') {
+    return createModifier('underline', { value: params });
+  }
+  return createModifier('underline', params);
+}

package/src/modifiers/unredacted.ts

@@ -0,0 +1,7 @@
+import { createModifier } from './createModifier';
+
+/// SwiftUI `.unredacted()`. Opts this view out of any redaction applied by
+/// an ancestor's `.redacted(reason:)`, rendering it normally.
+export function unredacted() {
+  return createModifier('unredacted');
+}

package/src/modifiers/watch.ts

@@ -0,0 +1,21 @@
+// "Watch-specific" modifiers — Digital Crown bindings and Apple Watch
+// hand-gesture / haptic affordances.
+export {
+  handGestureShortcut,
+  type HandGestureShortcutKind,
+  type HandGestureShortcutParams,
+} from './handGestureShortcut';
+export {
+  sensoryFeedback,
+  type SensoryFeedbackKind,
+  type SensoryFeedbackParams,
+} from './sensoryFeedback';
+export {
+  digitalCrownRotation,
+  type DigitalCrownSensitivity,
+  type DigitalCrownRotationParams,
+} from './digitalCrownRotation';
+export {
+  digitalCrownAccessory,
+  type DigitalCrownAccessoryParams,
+} from './digitalCrownAccessory';

package/src/modifiers/zIndex.ts

@@ -0,0 +1,20 @@
+import { createModifier } from './createModifier';
+
+export interface ZIndexParams {
+  /// Stacking order within the parent. Higher values render in front of
+  /// lower ones. Defaults to `0`.
+  value?: number;
+}
+
+/// SwiftUI `.zIndex(_:)`. Controls the front-to-back ordering of this view
+/// among overlapping siblings in the same container.
+export function zIndex(
+  params: ZIndexParams
+): ReturnType<typeof createModifier>;
+export function zIndex(value: number): ReturnType<typeof createModifier>;
+export function zIndex(a: ZIndexParams | number) {
+  if (typeof a === 'number') {
+    return createModifier('zIndex', { value: a });
+  }
+  return createModifier('zIndex', a);
+}

package/src/polyfills.ts

@@ -0,0 +1,206 @@
+// Globals required by the React scheduler + React's `act()` helper that
+// standard React Native installs from `InitializeCore.js → setUpTimers.js`.
+// The watch runtime doesn't run InitializeCore, so we install them here.
+//
+// Loaded as a side-effect import from `renderer/index.ts` and
+// `dev-support` — both run before React itself initializes.
+
+// Rich `console` shim — overrides the host's one-arg bootstrap with
+// multi-arg formatting. Loaded first so the rest of polyfills.ts (and the
+// rest of the bundle) gets the full behavior.
+import './setupConsole';
+
+// `globalThis.self` shim — must run before `whatwg-fetch` evaluates. Lives in
+// its own module so Babel's ESM hoisting doesn't reorder it after the
+// import. See setupSelfGlobal.ts for why.
+import './setupSelfGlobal';
+
+// WHATWG `fetch` + `Headers` + `Request` + `Response` polyfill. Reads
+// `globalThis.XMLHttpRequest`, which RNWHermesHost installs via
+// `rnwInstallXHR` before the bundle is evaluated.
+import 'whatwg-fetch';
+
+interface HermesInternalShape {
+  enablePromiseRejectionTracker?: (opts: {
+    allRejections: boolean;
+    onUnhandled?: (id: number, error: unknown) => void;
+    onHandled?: (id: number) => void;
+  }) => void;
+}
+
+interface ErrorUtilsShape {
+  setGlobalHandler: (fn: (error: unknown, isFatal: boolean) => void) => void;
+  getGlobalHandler: () => (error: unknown, isFatal: boolean) => void;
+  reportError: (error: unknown) => void;
+  reportFatalError: (error: unknown) => void;
+}
+
+const g = globalThis as unknown as {
+  setImmediate?: unknown;
+  clearImmediate?: unknown;
+  queueMicrotask?: (cb: () => void) => void;
+  setTimeout?: (cb: (...args: unknown[]) => void, ms: number) => number;
+  reportError?: (error: unknown) => void;
+  console?: {
+    error: (...args: unknown[]) => void;
+  };
+  HermesInternal?: HermesInternalShape;
+  ErrorUtils?: ErrorUtilsShape;
+};
+
+// Schedule a continuation as fast as possible. The watch host's
+// `RNWHermesHost.installTimers` registers `setTimeout` but NOT
+// `queueMicrotask`, so we prefer queueMicrotask when present and
+// fall back to `setTimeout(fn, 0)` otherwise. Without this fallback
+// callbacks were silently dropped — the runtime didn't crash but no
+// render work ever ran.
+function scheduleSoon(fn: () => void): void {
+  if (typeof g.queueMicrotask === 'function') {
+    g.queueMicrotask(fn);
+  } else if (typeof g.setTimeout === 'function') {
+    g.setTimeout(fn, 0);
+  } else {
+    throw new Error(
+      'No microtask scheduling primitive available (queueMicrotask / setTimeout). ' +
+        'The watch host bootstrap should install at least one.'
+    );
+  }
+}
+
+if (typeof g.setImmediate !== 'function') {
+  let nextId = 1;
+  const cleared = new Set<number>();
+  g.setImmediate = function setImmediate(
+    callback: (...args: unknown[]) => void,
+    ...args: unknown[]
+  ): number {
+    if (typeof callback !== 'function') {
+      throw new TypeError(
+        'setImmediate must be called with a function as the first argument'
+      );
+    }
+    const id = nextId++;
+    scheduleSoon(() => {
+      if (cleared.delete(id)) return;
+      callback(...args);
+    });
+    return id;
+  };
+  g.clearImmediate = function clearImmediate(id: number): void {
+    cleared.add(id);
+  };
+}
+
+// ----------------------------------------------------------------------------
+// Uncaught error reporting.
+//
+// On the watch, the native host catches C++ exceptions at the dispatch-block
+// boundary (setTimeout/setInterval callbacks, fireEventWithHandlerId, the
+// JS call invoker) but only NSLogs them — they never reach Metro and never
+// trigger the on-device error toast.
+//
+// Standard React Native installs `globalThis.ErrorUtils` + a `reportError`
+// + a Hermes promise-rejection tracker via `setUpErrorHandling.js`. We do
+// the same here, routing every uncaught error to `console.error`, which the
+// host already forwards to Metro AND publishes into the @Published `logs`
+// array (so the SwiftUI overlay can show the toast).
+// ----------------------------------------------------------------------------
+
+function formatError(error: unknown): { message: string; stack?: string } {
+  if (error instanceof Error) {
+    return { message: error.message || String(error), stack: error.stack };
+  }
+  if (typeof error === 'object' && error != null) {
+    const e = error as { message?: unknown; stack?: unknown };
+    return {
+      message:
+        typeof e.message === 'string' ? e.message : JSON.stringify(error),
+      stack: typeof e.stack === 'string' ? e.stack : undefined,
+    };
+  }
+  return { message: String(error) };
+}
+
+function logError(prefix: string, error: unknown): void {
+  const { message, stack } = formatError(error);
+  // console.error → RNWHermesHost.onConsoleLog → ReactNativeWatchOSHost
+  //                 publishes to `logs` + POSTs to /__watchos_log.
+  g.console?.error?.(`${prefix} ${message}${stack ? '\n' + stack : ''}`);
+}
+
+// `reportError` — Web platform standard; React 19's effect / setState
+// error path calls this when it can't propagate further. Hermes doesn't
+// ship it natively, so polyfill.
+if (typeof g.reportError !== 'function') {
+  g.reportError = (error: unknown) => logError('[reportError]', error);
+}
+
+// `ErrorUtils` — RN's legacy global. Metro auto-bundles a polyfill (see
+// `error-guard.js`) whose default handler simply rethrows the error,
+// which on the watch means it explodes at the C++ dispatch boundary
+// where the host only NSLogs. Override the handler to route to
+// `console.error` instead, so the existing onConsoleLog → Metro pipeline
+// catches it. If no ErrorUtils is present at all, install a minimal
+// shim with the same routing.
+if (g.ErrorUtils != null) {
+  g.ErrorUtils.setGlobalHandler((error, isFatal) => {
+    logError(isFatal ? '[ErrorUtils fatal]' : '[ErrorUtils]', error);
+  });
+} else {
+  let handler: (error: unknown, isFatal: boolean) => void = (
+    error,
+    isFatal
+  ) => {
+    logError(isFatal ? '[ErrorUtils fatal]' : '[ErrorUtils]', error);
+  };
+  g.ErrorUtils = {
+    setGlobalHandler: (fn) => {
+      handler = fn;
+    },
+    getGlobalHandler: () => handler,
+    reportError: (error) => handler(error, false),
+    reportFatalError: (error) => handler(error, true),
+  };
+}
+
+// Hermes promise-rejection tracker — fires on `Promise.reject(...)`
+// (or thrown inside async fn) that never gets a `.catch()` handler.
+// The host's native catch sees the C++ exception too late (after the
+// JS Promise machinery has already swallowed it), so the JS-side hook
+// is the only reliable signal.
+g.HermesInternal?.enablePromiseRejectionTracker?.({
+  allRejections: true,
+  onUnhandled: (id, error) => {
+    logError(`[UnhandledPromiseRejection #${id}]`, error);
+  },
+});
+
+// Wrap `setTimeout` so callbacks that throw don't tear the runtime
+// down at the dispatch-block C++ exception boundary (where the host
+// only NSLogs). React's scheduler runs via setTimeout (through our
+// `setImmediate` polyfill above), so this catches most React effect /
+// render errors and gets them to Metro.
+//
+// Reuses the captured `g.setTimeout` (Hermes' native host fn) — must
+// happen AFTER any reassignment / wrapping by RN polyfills.
+const nativeSetTimeout = g.setTimeout;
+if (typeof nativeSetTimeout === 'function') {
+  g.setTimeout = function setTimeout(
+    callback: (...args: unknown[]) => void,
+    ms: number,
+    ...args: unknown[]
+  ): number {
+    if (typeof callback !== 'function') {
+      return nativeSetTimeout(callback as never, ms);
+    }
+    return nativeSetTimeout(function wrapped(...inner: unknown[]) {
+      try {
+        callback(...(args.length > 0 ? args : inner));
+      } catch (e) {
+        logError('[setTimeout]', e);
+      }
+    }, ms);
+  } as typeof nativeSetTimeout;
+}
+
+export {};

package/src/reactNativeShim.ts

@@ -0,0 +1,113 @@
+// Stand-in for the `react-native` package on the watchos platform.
+//
+// `withWatchosMetro` aliases `react-native` → this file when the bundle's
+// platform is `watchos`. Without that redirect, Metro statically walks
+// `react-native/index.js` (every `require()` inside the lazy getters is
+// part of the dep graph) and ends up resolving `setUpReactDevTools.js` →
+// `ReactDevToolsSettingsManager`, a file RN only ships as `.android.js` /
+// `.ios.js`. No `.watchos.js` variant means the resolver fails to bundle.
+//
+// The watch runtime has no batched bridge, no UIManager, no DevTools — it
+// only has Hermes + `globalThis.__turboModuleProxy` installed by
+// `RNWHermesHost.installTurboModules`. So this shim deliberately exposes
+// only `TurboModuleRegistry` (and the `TurboModule` brand interface).
+// Other RN APIs would crash at runtime here.
+
+export interface TurboModule {}
+
+type TurboModuleProxy = <T extends TurboModule>(name: string) => T | null;
+
+function requireModule<T extends TurboModule>(name: string): T | null {
+  const proxy = (globalThis as { __turboModuleProxy?: TurboModuleProxy })
+    .__turboModuleProxy;
+  return proxy ? proxy<T>(name) : null;
+}
+
+export const TurboModuleRegistry = {
+  get<T extends TurboModule>(name: string): T | null {
+    return requireModule<T>(name);
+  },
+  getEnforcing<T extends TurboModule>(name: string): T {
+    const mod = requireModule<T>(name);
+    if (mod == null) {
+      throw new Error(
+        `TurboModuleRegistry.getEnforcing(...): '${name}' could not be found. ` +
+          `Verify that a module by this name is registered in the native binary.`
+      );
+    }
+    return mod;
+  },
+};
+
+/** Marker the JS facade for watch-only modules (e.g. WatchConnectivity)
+ *  uses to detect which platform's event-delivery path to install.
+ *  Standard `react-native` doesn't define this; the shim does. */
+export const IS_WATCHOS = true;
+
+/** Stub for `Platform` so consumer code that does
+ *  `import { Platform } from 'react-native'` on watchOS doesn't crash
+ *  at the import site. Anything reading `Platform.OS` gets `'watchos'`. */
+export const Platform = {
+  OS: 'watchos' as const,
+  select: <T>(specifics: { default?: T; watchos?: T }): T | undefined =>
+    specifics.watchos ?? specifics.default,
+};
+
+/**
+ * Functional `NativeEventEmitter` stub. Mirrors the iOS RN API so the
+ * same JS facade works on both platforms unchanged:
+ *
+ *   const emitter = new NativeEventEmitter(NativeMyModule);
+ *   const sub = emitter.addListener('foo', payload => { ... });
+ *   sub.remove();
+ *
+ * Under the hood on watchOS:
+ *   - `addListener(name, fn)` registers `fn` in the shared name-keyed
+ *     listener registry (`eventRegistry`).
+ *   - `sendEventWithName:body:` on the native side posts a notification
+ *     carrying the event name; the Swift host forwards into
+ *     `__RNW_EVENTS.dispatchEvent(name, payload)`, which fans out to
+ *     every registered listener for that name.
+ *   - No native handshake — the native module never learns about
+ *     individual listeners. `addListener` / `removeListeners` on the
+ *     native side are called for parity with RN's contract but are
+ *     no-ops in the watch stub.
+ */
+type ShimListener = (payload?: unknown) => void;
+
+interface ShimNativeModule {
+  addListener?(eventName: string): void;
+  removeListeners?(count: number): void;
+}
+
+export class NativeEventEmitter {
+  private readonly _nativeModule: ShimNativeModule;
+
+  constructor(nativeModule: ShimNativeModule) {
+    this._nativeModule = nativeModule;
+  }
+
+  addListener(
+    eventName: string,
+    listener: ShimListener
+  ): { remove: () => void } {
+    // Lazy-require to break the circular dep: eventRegistry imports
+    // the JS runtime globals installed by RNWHermesHost, and pulling
+    // it eagerly would crash if the shim is loaded before the host.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { registerEventListener, installEventBridge } =
+      require('./eventRegistry') as typeof import('./eventRegistry');
+    // Make sure `__RNW_EVENTS.dispatchEvent` is installed even when the
+    // consumer imports this shim without also importing the renderer.
+    installEventBridge();
+
+    const dispose = registerEventListener(eventName, listener);
+    this._nativeModule.addListener?.(eventName);
+    return {
+      remove: () => {
+        dispose();
+        this._nativeModule.removeListeners?.(1);
+      },
+    };
+  }
+}