@granite-js/react-native 0.0.0-dev-20250725013859

package/src/intersection-observer/withIO.tsx

@@ -0,0 +1,151 @@
+import { type ComponentProps, PureComponent, RefObject, createRef } from 'react';
+import { LayoutChangeEvent, NativeScrollEvent, NativeSyntheticEvent, ScrollView, findNodeHandle } from 'react-native';
+import IOContext, { IOContextValue } from './IOContext';
+import IOManager from './IOManager';
+import { Root, RootMargin } from './IntersectionObserver';
+
+export interface IOComponentProps {
+  rootMargin?: RootMargin;
+}
+
+/**
+ * @category Functions
+ * @kind function
+ * @name withIO
+ * @description
+ * A Higher-Order Component (HoC) that wraps a component with `IOContext` to enable Intersection Observer functionality.
+ *
+ * @argument
+ * @param {React.ComponentType} [BaseComponent] - Callback function that is called when the component is mounted.
+ * @param {string[]} [methods] - List of event handler names from BaseComponent to be bound.
+ * @returns {React.ComponentType} - Returns a wrapped component that can use Intersection Observer functionality.
+ */
+function withIO<
+  CompProps extends Pick<
+    ComponentProps<typeof ScrollView>,
+    'horizontal' | 'scrollEventThrottle' | 'onContentSizeChange' | 'onLayout' | 'onScroll'
+  >,
+>(BaseComponent: React.ComponentType<CompProps>, methods: string[]) {
+  type ScrollableComponentProps = CompProps & IOComponentProps;
+  const IOScrollableComponent = class extends PureComponent<ScrollableComponentProps> {
+    protected node: any;
+    protected scroller: RefObject<any>;
+    protected root: Root;
+    protected manager: IOManager;
+    protected contextValue: IOContextValue;
+
+    constructor(props: ScrollableComponentProps) {
+      super(props);
+
+      // eslint-disable-next-line @typescript-eslint/no-this-alias
+      const self = this;
+      this.scroller = createRef();
+      this.root = {
+        get node() {
+          return self.node;
+        },
+        get horizontal() {
+          return Boolean(self.props.horizontal);
+        },
+        current: {
+          contentInset: {
+            top: 0,
+            right: 0,
+            bottom: 0,
+            left: 0,
+          },
+          contentOffset: {
+            x: 0,
+            y: 0,
+          },
+          contentSize: {
+            width: 0,
+            height: 0,
+          },
+          layoutMeasurement: {
+            width: 0,
+            height: 0,
+          },
+          zoomScale: 1,
+        },
+      };
+      const manager = new IOManager({
+        root: this.root,
+        get rootMargin() {
+          return self.props.rootMargin;
+        },
+      });
+      this.manager = manager;
+      this.contextValue = {
+        manager,
+      };
+    }
+
+    componentDidMount() {
+      this.node = findNodeHandle(this.scroller.current);
+      methods.forEach((method) => {
+        (this as any)[method] = (...args: any) => {
+          this.scroller.current?.[method]?.(...args);
+        };
+      });
+    }
+
+    protected handleContentSizeChange = (width: number, height: number) => {
+      const { contentSize } = this.root.current;
+      if (width !== contentSize.width || height !== contentSize.height) {
+        this.root.current.contentSize = { width, height };
+        if (width > 0 && height > 0 && this.root.onLayout) {
+          this.root.onLayout();
+        }
+      }
+      const { onContentSizeChange } = this.props;
+      if (onContentSizeChange) {
+        onContentSizeChange(width, height);
+      }
+    };
+
+    protected handleLayout = (event: LayoutChangeEvent) => {
+      const {
+        nativeEvent: { layout },
+      } = event;
+      const { layoutMeasurement } = this.root.current;
+      if (layoutMeasurement.width !== layout.width || layoutMeasurement.height !== layout.height) {
+        this.root.current.layoutMeasurement = layout;
+      }
+      const { onLayout } = this.props;
+      if (onLayout) {
+        onLayout(event);
+      }
+    };
+
+    protected handleScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+      this.root.current = event.nativeEvent;
+      if (this.root.onScroll) {
+        this.root.onScroll(this.root.current);
+      }
+      const { onScroll } = this.props;
+      if (onScroll) {
+        onScroll(event);
+      }
+    };
+
+    render() {
+      return (
+        <IOContext.Provider value={this.contextValue}>
+          <BaseComponent
+            scrollEventThrottle={16}
+            {...this.props}
+            ref={this.scroller}
+            onContentSizeChange={this.handleContentSizeChange}
+            onLayout={this.handleLayout}
+            onScroll={this.handleScroll}
+          />
+        </IOContext.Provider>
+      );
+    }
+  };
+
+  return IOScrollableComponent as typeof BaseComponent;
+}
+
+export default withIO;

package/src/jest/index.ts

@@ -0,0 +1 @@
+export { setup, config } from '@granite-js/jest';

package/src/keyboard/KeyboardAboveView.tsx

@@ -0,0 +1,62 @@
+import { ComponentProps, ReactElement } from 'react';
+import { Animated, View } from 'react-native';
+import { useKeyboardAnimatedHeight } from './useKeyboardAnimatedHeight';
+
+/**
+ * @public
+ * @category UI
+ * @name KeyboardAboveView
+ * @kind function
+ * @description
+ * A component that automatically lifts child components above the keyboard when it appears on the screen.
+ * It's useful when you want to keep elements like a "Send" button fixed above the keyboard during text input.
+ *
+ * @param {StyleProp<ViewStyle>} [props.style] - Additional styles can be applied. For example, you can set background color or size.
+ * @param {ReactNode} [props.children] - Components to be displayed above the keyboard when it appears. For example, you can include buttons, text input fields, etc.
+ * @returns {ReactElement} - Returns an [`Animated.View`](https://reactnative.dev/docs/animated#createanimatedcomponent) that is adjusted above the keyboard when it appears.
+ * @example
+ *
+ * ### Lifting elements above the keyboard
+ *
+ * ```tsx
+ * import { ScrollView, TextInput, View, Text } from 'react-native';
+ * import { KeyboardAboveView } from '@granite-js/react-native';
+ *
+ * export function KeyboardAboveViewExample() {
+ *   return (
+ *     <>
+ *       <ScrollView>
+ *         <TextInput placeholder="placeholder" />
+ *       </ScrollView>
+ *
+ *       <KeyboardAboveView>
+ *         <View style={{ width: '100%', height: 50, backgroundColor: 'yellow' }}>
+ *           <Text>Above the keyboard</Text>
+ *         </View>
+ *       </KeyboardAboveView>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function KeyboardAboveView({ style, children, ...props }: ComponentProps<typeof View>): ReactElement {
+  const keyboardHeight = useKeyboardAnimatedHeight();
+
+  return (
+    <Animated.View
+      style={[
+        style,
+        {
+          transform: [
+            {
+              translateY: Animated.subtract(0, keyboardHeight),
+            },
+          ],
+        },
+      ]}
+      {...props}
+    >
+      {children}
+    </Animated.View>
+  );
+}

package/src/keyboard/index.ts

@@ -0,0 +1,2 @@
+export { KeyboardAboveView } from './KeyboardAboveView';
+export { useKeyboardAnimatedHeight } from './useKeyboardAnimatedHeight';

package/src/keyboard/useKeyboardAnimatedHeight.tsx

@@ -0,0 +1,81 @@
+import { useEffect, useRef } from 'react';
+import { Animated, Keyboard, Platform } from 'react-native';
+
+function getInitialKeyboardHeight() {
+  if (Platform.OS !== 'ios') {
+    return 0;
+  }
+
+  /**
+   * Branch handling for React Native 0.68.0 version where `metrics()` does not exist
+   */
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  if (typeof Keyboard?.metrics === 'function') {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return Keyboard.metrics()?.height ?? 0;
+  } else {
+    return 0;
+  }
+}
+
+/**
+ * @category Hooks
+ * @name useKeyboardAnimatedHeight
+ * @description
+ * A Hook that returns an animatable value (`Animated.Value`) representing the keyboard height changes when the keyboard appears or disappears. You can smoothly animate UI elements according to the keyboard height as it rises or falls.
+ *
+ * This Hook is primarily used on iOS. On Android, it does not detect keyboard height changes and always returns an `Animated.Value` with an initial value of `0`. In other words, animations are not applied in the Android environment.
+ *
+ * @returns {Animated.Value} - An animation value representing the keyboard height.
+ * @example
+ * ```typescript
+ * const keyboardHeight = useKeyboardAnimatedHeight();
+ *
+ * <Animated.View style={{ marginBottom: keyboardHeight }}>
+ *  {children}
+ * </Animated.View>
+ * ```
+ */
+export function useKeyboardAnimatedHeight(): Animated.Value {
+  const keyboardHeight = useRef(new Animated.Value(getInitialKeyboardHeight())).current;
+
+  useEffect(() => {
+    if (Platform.OS === 'ios') {
+      const willShowSubscription = Keyboard.addListener('keyboardWillShow', (event) => {
+        const height = event.endCoordinates.height;
+
+        Animated.spring(keyboardHeight, {
+          toValue: height,
+          useNativeDriver: true,
+          ...spring.quick,
+        }).start();
+      });
+
+      const willHideSubscription = Keyboard.addListener('keyboardWillHide', () => {
+        Animated.spring(keyboardHeight, {
+          toValue: 0,
+          useNativeDriver: true,
+          ...spring.quick,
+        }).start();
+      });
+      return () => {
+        willShowSubscription.remove();
+        willHideSubscription.remove();
+      };
+    } else {
+      return;
+    }
+  }, [keyboardHeight]);
+
+  return keyboardHeight;
+}
+
+const spring = {
+  quick: {
+    stiffness: 800,
+    damping: 55,
+    mass: 1,
+  },
+};

package/src/native-event-emitter/eventEmitters/index.ts

@@ -0,0 +1,3 @@
+import { VisibilityChangedEventEmitter } from './visibilityChanged';
+
+export type EventEmitters = VisibilityChangedEventEmitter;

package/src/native-event-emitter/eventEmitters/types.ts

@@ -0,0 +1,4 @@
+export interface EventEmitterSchema<K extends string, P extends unknown[]> {
+  name: K;
+  params: P;
+}

package/src/native-event-emitter/eventEmitters/visibilityChanged.ts

@@ -0,0 +1,11 @@
+import { EventEmitterSchema } from './types';
+
+/**
+ * @name VisibilityChangedEventEmitter
+ * @kind typedef
+ * @platform iOS
+ * @description
+ * Emits an event when the visibility state of the app changes.
+ * Only available on iOS.
+ */
+export type VisibilityChangedEventEmitter = EventEmitterSchema<'visibilityChanged', [boolean]>;

package/src/native-event-emitter/index.ts

@@ -0,0 +1 @@
+export * from './nativeEventEmitter';

package/src/native-event-emitter/nativeEventEmitter.ts

@@ -0,0 +1,18 @@
+import { EmitterSubscription, NativeEventEmitter } from 'react-native';
+import { EventEmitters } from './eventEmitters';
+import { GraniteCoreModule } from '../native-modules';
+import { EventEmitterSchema } from './eventEmitters/types';
+
+type MapOf<T> = T extends EventEmitterSchema<infer K, any> ? { [key in K]: T } : never;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type EventEmittersMap = UnionToIntersection<MapOf<EventEmitters>>;
+type EventKeys = keyof EventEmittersMap;
+type ParamOf<K extends EventKeys> = EventEmittersMap[K]['params'];
+interface EventEmitter {
+  addListener<Event extends EventKeys>(
+    event: Event,
+    callback: (...params: ParamOf<Event>) => void
+  ): EmitterSubscription;
+}
+
+export const nativeEventEmitter = new NativeEventEmitter(GraniteCoreModule) as unknown as EventEmitter;

package/src/native-modules/core/GraniteCoreModule.ts

@@ -0,0 +1,9 @@
+import { TurboModule, TurboModuleRegistry } from 'react-native';
+
+interface GraniteCoreModule extends TurboModule {
+  addListener: (eventType: string) => void;
+  removeListeners: (count: number) => void;
+  importLazy: () => Promise<void>;
+}
+
+export const GraniteCoreModule = TurboModuleRegistry.getEnforcing<GraniteCoreModule>('GraniteCoreModule');

package/src/native-modules/index.ts

@@ -0,0 +1,3 @@
+/** Bridges API */
+export * from './natives';
+export { GraniteCoreModule } from './core/GraniteCoreModule';

package/src/native-modules/natives/GraniteModule.ts

@@ -0,0 +1,8 @@
+import { TurboModule, TurboModuleRegistry } from 'react-native';
+
+interface GraniteModuleSpec extends TurboModule {
+  closeView: () => void;
+  schemeUri: string;
+}
+
+export const GraniteModule = TurboModuleRegistry.getEnforcing<GraniteModuleSpec>('GraniteModule');

package/src/native-modules/natives/closeView.ts

@@ -0,0 +1,25 @@
+import { GraniteModule } from './GraniteModule';
+
+/**
+ * @public
+ * @category Screen Control
+ * @kind function
+ * @name closeView
+ * @description Function that closes the current screen. It can be used when you want to exit a service by pressing a "Close" button.
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ### Close screen with close button
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { closeView } from '@granite-js/react-native';
+ *
+ * function CloseButton() {
+ *  return <Button title="Close" onPress={closeView} />;
+ * }
+ * ```
+ */
+export async function closeView() {
+  return GraniteModule.closeView();
+}

package/src/native-modules/natives/getSchemeUri.ts

@@ -0,0 +1,27 @@
+import { GraniteModule } from './GraniteModule';
+
+/**
+ * @public
+ * @name getSchemeUri
+ * @category Environment Check
+ * @kind function
+ * @description Returns the scheme value when first entering the screen. URI changes due to page navigation are not reflected.
+ * @returns {string} Returns the scheme value when first entering the screen.
+ *
+ * @example
+ * ### Get initial scheme value
+ *
+ * ```tsx
+ * import { getSchemeUri } from '@granite-js/react-native';
+ * import { Text } from 'react-native';
+ *
+ * function MyPage() {
+ *  const schemeUri = getSchemeUri();
+ *
+ *  return <Text>Initial scheme value: {schemeUri}</Text>
+ * }
+ * ```
+ */
+export function getSchemeUri() {
+  return GraniteModule.schemeUri;
+}

package/src/native-modules/natives/index.ts

@@ -0,0 +1,3 @@
+export * from './closeView';
+export * from './getSchemeUri';
+export * from './openURL';

package/src/native-modules/natives/openURL.ts

@@ -0,0 +1,40 @@
+import { Linking } from 'react-native';
+
+/**
+ * @public
+ * @kind function
+ * @category Screen Navigation
+ *
+ * @name openURL
+ * @signature
+ * ```typescript
+ * function openURL(url: string): Promise<any>;
+ * ```
+ *
+ * @description
+ * Opens the specified URL in the device's default browser or related app.
+ * This function uses the [`Linking.openURL`](https://reactnative.dev/docs/0.72/linking#openurl) method from `react-native` to open the URL.
+ *
+ * @param {string} url URL address to open
+ * @returns {Promise<any>} Promise that resolves when the URL is successfully opened
+ *
+ * @example
+ *
+ * ### Open external URL
+ *
+ * ```tsx
+ * import { openURL } from '@granite-js/react-native';
+ * import { Button } from 'react-native';
+ *
+ * function Page() {
+ *   const handlePress = () => {
+ *     openURL('https://google.com');
+ *   };
+ *
+ *   return <Button title="Open Google Website" onPress={handlePress} />;
+ * }
+ * ```
+ */
+export function openURL(url: string): Promise<any> {
+  return Linking.openURL(url);
+}

package/src/react/index.ts

@@ -0,0 +1 @@
+export { useWaitForReturnNavigator } from './useWaitForReturnNavigator';

package/src/react/useWaitForReturnNavigator.ts

@@ -0,0 +1,75 @@
+import { useNavigation } from '@granite-js/native/@react-navigation/native';
+import { NativeStackNavigationProp } from '@granite-js/native/@react-navigation/native-stack';
+import { useCallback, useRef } from 'react';
+import { useVisibilityChange, type VisibilityState } from '../visibility';
+
+/**
+ * @public
+ * @category Screen Control
+ * @name useWaitForReturnNavigator
+ * @description
+ * A Hook that helps execute the next code synchronously when returning from a screen transition.
+ * Screen navigation uses [@react-navigation/native `useNavigation`'s `navigate`](https://reactnavigation.org/docs/6.x/navigation-prop#navigate).
+ *
+ * For example, it can be used when you want to log that a user has navigated to another screen and returned.
+ *
+ * @example
+ * ### Example of code execution when returning from screen navigation
+ *
+ * When the **"Navigate"** button is pressed, it navigates to another screen, and logs are created when returning.
+ *
+ * ```tsx
+ * import { Button } from 'react-native';
+ * import { useWaitForReturnNavigator } from '@granite-js/react-native';
+ *
+ * export function UseWaitForReturnNavigator() {
+ *   const navigate = useWaitForReturnNavigator();
+ *
+ *   return (
+ *     <>
+ *       <Button
+ *         title="Navigate"
+ *         onPress={async () => {
+ *           console.log(1);
+ *           await navigate('/examples/use-visibility');
+ *           // This code executes when returning to the screen
+ *           console.log(2);
+ *         }}
+ *       />
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+
+export function useWaitForReturnNavigator<T extends Record<string, object | undefined>>() {
+  const callbacks = useRef<Array<() => void>>([]).current;
+  const navigation = useNavigation<NativeStackNavigationProp<T>>();
+
+  const startNavigating = useCallback(
+    <RouteName extends keyof T>(route: RouteName, params?: T[RouteName]): Promise<void> => {
+      return new Promise<void>((resolve) => {
+        callbacks.push(resolve);
+        navigation.navigate(route as any, params as any);
+      });
+    },
+    [callbacks, navigation]
+  );
+
+  const handleVisibilityChange = useCallback(
+    (state: VisibilityState) => {
+      if (state === 'visible' && callbacks.length > 0) {
+        for (const callback of callbacks) {
+          callback();
+        }
+
+        callbacks.splice(0, callbacks.length);
+      }
+    },
+    [callbacks]
+  );
+
+  useVisibilityChange(handleVisibilityChange);
+
+  return startNavigating;
+}

package/src/rn-polyfills/index.ts

@@ -0,0 +1,7 @@
+import { setup as setupSymbolAsyncIterator } from './symbol-asynciterator';
+import { setup as setupURLPolyfill } from './url';
+
+export function setup() {
+  setupSymbolAsyncIterator();
+  setupURLPolyfill();
+}

package/src/rn-polyfills/symbol-asynciterator/index.ts

@@ -0,0 +1,15 @@
+/**
+ * Polyfill for @swc/helpers build compatibility
+ *
+ * @see https://github.com/swc-project/swc/blob/v1.4.15/packages/helpers/esm/_async_iterator.js#L3
+ *
+ * - babel: No runtime issues after build as there is a fallback for `Symbol.asyncIterator`
+ * - swc: No fallback for `Symbol.asyncIterator`, so it needs to be defined in advance
+ */
+export function setup() {
+  if (typeof Symbol !== 'undefined' && !Symbol.asyncIterator) {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    Symbol.asyncIterator = Symbol.for('@@asyncIterator');
+  }
+}

package/src/rn-polyfills/url/index.ts

@@ -0,0 +1 @@
+export { setupURLPolyfill as setup } from 'react-native-url-polyfill';