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

package/src/intersection-observer/IOFlatList.ts

@@ -0,0 +1,72 @@
+import { RefAttributes } from 'react';
+import { FlatList, FlatListProps } from 'react-native';
+import withIO, { IOComponentProps } from './withIO';
+
+export type IOFlatListController = FlatList;
+
+export type IOFlatListProps<ItemT = any> = IOComponentProps & FlatListProps<ItemT>;
+
+/**
+ * @public
+ * @category Screen Control
+ * @name IOFlatList
+ * @description
+ * `IOFlatList` is a `FlatList` component with added Intersection Observer functionality to detect when specific elements become visible or disappear from the screen during scrolling. Using this component, you can easily check and handle whether each item in the list is visible on the screen.
+ *
+ * When used with `InView`, you can check the exposure status of each element. The [InView](/reference/react-native/Screen%20Control/InView) component included as a child element detects whether the element is visible on the screen through the observation functionality of `IOFlatList` and triggers events based on the exposure status.
+ *
+ * @example
+ *
+ * You can check whether each item in the list appears on the screen using `IOFlatList`.
+ * When each item in the list appears on the screen, the `InView` component changes to the `visible` state.
+ *
+ * ```tsx
+ * import { ReactNode, useState } from 'react';
+ * import { StyleSheet, Text, View } from 'react-native';
+ * import { InView, IOFlatList } from '@granite-js/react-native';
+ *
+ * const mockData = Array.from({ length: 30 }, (_, i) => ({ key: String(i) }));
+ *
+ * export default function FlatListPage() {
+ *  return <IOFlatList data={mockData} renderItem={({ item }) => <InViewItem>{item.key}</InViewItem>} />;
+ * }
+ *
+ * function InViewItem({ children }: { children: ReactNode }) {
+ *  const [visible, setVisible] = useState(false);
+ *
+ *  return (
+ *    <InView onChange={setVisible}>
+ *      <View style={styles.item}>
+ *        <Text>{children}</Text>
+ *        <Text>{visible ? 'visible' : ''}</Text>
+ *      </View>
+ *    </InView>
+ *  );
+ * }
+ *
+ * const styles = StyleSheet.create({
+ *  item: {
+ *    padding: 16,
+ *    borderBottomWidth: 1,
+ *    borderBottomColor: '#ddd',
+ *  },
+ * });
+ * ```
+ */
+const IOFlatList = withIO(FlatList, [
+  'flashScrollIndicators',
+  'getNativeScrollRef',
+  'getScrollResponder',
+  'getScrollableNode',
+  'scrollToEnd',
+  'scrollToIndex',
+  'scrollToItem',
+  'scrollToOffset',
+]) as unknown as typeof IOFlatListFunction;
+
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+declare function IOFlatListFunction<ItemT = any>(
+  props: IOFlatListProps<ItemT> & RefAttributes<IOFlatListController>
+): JSX.Element;
+
+export default IOFlatList;

package/src/intersection-observer/IOManager.ts

@@ -0,0 +1,73 @@
+import IntersectionObserver, {
+  IntersectionObserverOptions,
+  IntersectionObserverEntry,
+  Element,
+} from './IntersectionObserver';
+
+export type ObserverInstanceCallback = (inView: boolean, intersectionRatio: number) => void;
+
+export interface ObserverInstance {
+  readonly callback: ObserverInstanceCallback;
+  readonly element: Element;
+  readonly observerId: number;
+  readonly observer: IntersectionObserver;
+}
+
+/**
+ * @kind class
+ * @name IOManager
+ * @description A class that tracks the visibility of DOM elements using `IntersectionObserver` instances and executes callbacks when elements enter or leave the viewport.
+ * This class makes it easy to manage multiple elements and execute custom logic based on the visibility status of each element.
+ */
+class IOManager {
+  io: IntersectionObserver;
+  observerId: number;
+  instanceMap: Map<Element, ObserverInstance> = new Map();
+
+  constructor(options: IntersectionObserverOptions) {
+    this.io = new IntersectionObserver(this.handleChange, options);
+    this.observerId = 0;
+  }
+
+  handleChange = (entries: IntersectionObserverEntry[]) => {
+    for (let index = 0; index < entries.length; index += 1) {
+      const entry = entries[index];
+
+      if (entry == null) {
+        continue;
+      }
+
+      const { target, isIntersecting, intersectionRatio } = entry;
+      const instance = this.instanceMap.get(target);
+      if (instance) {
+        instance.callback(isIntersecting, intersectionRatio);
+      }
+    }
+  };
+
+  observe(element: Element, callback: ObserverInstanceCallback): ObserverInstance {
+    const existInstance = this.instanceMap.get(element);
+    if (existInstance) {
+      return existInstance;
+    }
+    this.observerId += 1;
+    const instance: ObserverInstance = {
+      callback,
+      element,
+      observerId: this.observerId,
+      observer: this.io,
+    };
+    this.instanceMap.set(element, instance);
+    this.io.observe(element);
+    return instance;
+  }
+
+  unobserve(element: any) {
+    if (this.instanceMap.has(element)) {
+      this.instanceMap.delete(element);
+      this.io.unobserve(element);
+    }
+  }
+}
+
+export default IOManager;

package/src/intersection-observer/IOScrollView.ts

@@ -0,0 +1,69 @@
+import { ForwardRefExoticComponent, RefAttributes } from 'react';
+import { ScrollView, ScrollViewProps } from 'react-native';
+import withIO, { IOComponentProps } from './withIO';
+
+export type IOScrollViewController = ScrollView;
+
+export type IOScrollViewProps = IOComponentProps & ScrollViewProps;
+
+/**
+ * @public
+ * @category Screen Control
+ * @name IOScrollView
+ * @description
+ * `IOScrollView` is a [ScrollView](https://reactnative.dev/docs/scrollview) component with added `Intersection Observer` functionality. It can detect when specific elements become visible or disappear from the screen during scrolling.
+ * By utilizing this functionality with the `InView` component as a child element, you can easily check whether elements are exposed on the screen.
+ *
+ * @example
+ *
+ * You can check whether each item in the list appears on the screen using `IOScrollView`.
+ * When each item in the list appears on the screen, the `InView` component changes to the `visible` state.
+ *
+ * ```tsx
+ * import { ReactNode, useState } from 'react';
+ * import { StyleSheet, Text, View } from 'react-native';
+ * import { InView, IOScrollView } from '@granite-js/react-native';
+ *
+ * const mockData = Array.from({ length: 30 }, (_, i) => ({ key: String(i) }));
+ *
+ * export default function IOScrollViewPage() {
+ *  return (
+ *    <IOScrollView>
+ *      {mockData.map((data) => (
+ *        <InViewItem key={data.key}>{data.key}</InViewItem>
+ *      ))}
+ *    </IOScrollView>
+ *  );
+ * }
+ *
+ * function InViewItem({ children }: { children: ReactNode }) {
+ *  const [visible, setVisible] = useState(false);
+ *
+ *  return (
+ *    <InView onChange={setVisible}>
+ *      <View style={styles.item}>
+ *        <Text>{children}</Text>
+ *        <Text>{visible ? 'visible' : ''}</Text>
+ *      </View>
+ *    </InView>
+ *  );
+ * }
+ *
+ * const styles = StyleSheet.create({
+ *  item: {
+ *    padding: 16,
+ *    borderBottomWidth: 1,
+ *    borderBottomColor: '#ddd',
+ *  },
+ * });
+ * ```
+ */
+const IOScrollView = withIO(ScrollView, [
+  'scrollTo',
+  'scrollToEnd',
+  'getScrollResponder',
+  'getScrollableNode',
+  'getInnerViewNode',
+]) as unknown as ForwardRefExoticComponent<IOScrollViewProps & RefAttributes<IOScrollViewController>>;
+
+export default IOScrollView;

package/src/intersection-observer/InView.tsx

@@ -0,0 +1,205 @@
+import { ComponentType, PureComponent, ReactElement, ReactNode, RefObject } from 'react';
+import { LayoutChangeEvent, View, ViewProps } from 'react-native';
+import IOContext, { IOContextValue } from './IOContext';
+import { ObserverInstance } from './IOManager';
+import { Element } from './IntersectionObserver';
+
+export interface RenderProps {
+  inView: boolean;
+  onChange: (inView: boolean) => void;
+}
+
+export interface Props {
+  [key: string]: any;
+}
+
+export type InViewProps<T = Props> = T & {
+  children: ReactNode | ((fields: RenderProps) => ReactElement<View>);
+  as?: ComponentType<any>;
+  triggerOnce?: boolean;
+  onLayout?: (event: LayoutChangeEvent) => void;
+  onChange?: (inView: boolean, areaThreshold: number) => void;
+};
+
+export type InViewWrapper = ComponentType<{
+  ref?: RefObject<any> | ((ref: any) => void);
+  onLayout?: (event: LayoutChangeEvent) => void;
+}>;
+
+/**
+ * @public
+ * @category Screen Control
+ * @name InView
+ * @description
+ * The `InView` component detects when an element starts to become visible on the screen or disappears from the screen.
+ * When an element starts to become visible on the screen, the `onChanged` handler is called with `true` as the first argument. Conversely, when the element disappears from the screen, `false` is passed.
+ * The second argument of the `onChanged` handler receives the exposure ratio of the element on the screen. The exposure ratio value ranges from `0` to `1.0`. For example, if `0.2` is passed, it means the component is 20% exposed on the screen.
+ *
+::: warning Note
+
+`InView` must be used inside [IOScrollView](/reference/react-native/Screen%20Control/InView.md) or [IOFlatList](/reference/react-native/Screen%20Control/IOFlatList.md) that includes `IOContext`.
+If used outside of `IOContext`, an `IOProviderMissingError` will occur.
+
+:::
+
+ * @param {Object} props - Props object passed to the component.
+ * @param {React.ReactNode} props.children - Child components to be rendered under the component.
+ * @param {React.ComponentType} [prop.as=View] - Specifies the component to actually render. Default is the [View](https://reactnative.dev/docs/view) component.
+ * @param {boolean} [triggerOnce=false] - Use this option if you want to call the `onChange` callback only once when the element first becomes visible.
+ * @param {(event: LayoutChangeEvent) => void} [onLayout] - Callback function called when there is a change in the layout.
+ * @param {(inView: boolean, areaThreshold: number) => void} [onChange] - Callback function called when an element appears or disappears from the screen. The first argument receives the visibility status, and the second argument receives the exposure ratio.
+ * 
+ * @example
+ * 
+ * ### Detecting the `10%` point of an element using the `InView` component
+ * 
+ * ```tsx
+ * import { LayoutChangeEvent, View, Text, Dimensions } from 'react-native';
+ * import { InView, IOScrollView } from '@granite-js/react-native';
+ * 
+ * export function InViewExample() {
+ *   const handleLayout = (event: LayoutChangeEvent) => {
+ *     console.log('Layout changed', event.nativeEvent.layout);
+ *   };
+ * 
+ *   const handleChange = (inView: boolean, areaThreshold: number) => {
+ *     if (inView) {
+ *       console.log(`Element is visible at ${areaThreshold * 100}% ratio`);
+ *     } else {
+ *       console.log('Element is not visible');
+ *     }
+ *   };
+ * 
+ *   return (
+ *     <IOScrollView>
+ *       <View style={{ height: HEIGHT, width: '100%', backgroundColor: 'blue' }}>
+ *         <Text style={{ color: 'white' }}>Please scroll down</Text>
+ *       </View>
+ *       <InView onLayout={handleLayout} onChange={handleChange}>
+ *         <View style={{ width: 100, height: 300, backgroundColor: 'yellow' }}>
+ *           <View style={{ position: 'absolute', top: 30, width: 100, height: 1, borderWidth: 1 }}>
+ *             <Text style={{ position: 'absolute', top: 0 }}>10% point</Text>
+ *           </View>
+ *         </View>
+ *       </InView>
+ *     </IOScrollView>
+ *   );
+ * }
+ * ```
+ */
+class InView<T = ViewProps> extends PureComponent<InViewProps<T>> {
+  static contextType = IOContext;
+  static defaultProps: Partial<InViewProps> = {
+    triggerOnce: false,
+    as: View,
+  };
+
+  context: undefined | IOContextValue = undefined;
+  mounted = false;
+
+  protected element: Element;
+  protected instance: undefined | ObserverInstance;
+  protected view: any;
+
+  constructor(props: InViewProps<T>) {
+    super(props);
+
+    this.element = {
+      inView: false,
+      intersectionRatio: 0,
+      layout: {
+        x: 0,
+        y: 0,
+        width: 0,
+        height: 0,
+      },
+      measureLayout: this.measureLayout,
+    };
+  }
+
+  componentDidMount() {
+    this.mounted = true;
+    if (this.context?.manager) {
+      this.instance = this.context.manager.observe(this.element, this.handleChange);
+    }
+  }
+
+  componentWillUnmount() {
+    this.mounted = false;
+    if (this.context?.manager && this.instance) {
+      this.context.manager.unobserve(this.element);
+    }
+  }
+
+  protected handleChange = (inView: boolean, areaThreshold: number) => {
+    if (this.mounted) {
+      const { triggerOnce, onChange } = this.props;
+      if (inView && triggerOnce) {
+        if (this.context?.manager) {
+          this.context?.manager.unobserve(this.element);
+        }
+      }
+      if (onChange) {
+        onChange(inView, areaThreshold);
+      }
+    }
+  };
+
+  protected handleRef = (ref: any) => {
+    this.view = ref;
+  };
+
+  protected handleLayout = (event: LayoutChangeEvent) => {
+    const {
+      nativeEvent: { layout },
+    } = event;
+    if (layout.width !== this.element.layout.width || layout.height !== this.element.layout.height) {
+      if (this.element.onLayout) {
+        this.element.onLayout();
+      }
+    }
+    const { onLayout } = this.props;
+    if (onLayout) {
+      onLayout(event);
+    }
+  };
+
+  measure = (...args: any) => {
+    this.view.measure(...args);
+  };
+
+  measureInWindow = (...args: any) => {
+    this.view.measureInWindow(...args);
+  };
+
+  measureLayout = (...args: any) => {
+    this.view.measureLayout(...args);
+  };
+
+  setNativeProps = (...args: any) => {
+    this.view.setNativeProps(...args);
+  };
+
+  focus = (...args: any) => {
+    this.view.focus(...args);
+  };
+
+  blur = (...args: any) => {
+    this.view.blur(...args);
+  };
+
+  render() {
+    const { as, children, ...props } = this.props;
+    if (typeof children === 'function') {
+      return null;
+    }
+    const ViewComponent: InViewWrapper = (as || View) as InViewWrapper;
+    return (
+      <ViewComponent {...props} ref={this.handleRef} onLayout={this.handleLayout}>
+        {children}
+      </ViewComponent>
+    );
+  }
+}
+
+export default InView;

package/src/intersection-observer/IntersectionObserver.ts

@@ -0,0 +1,212 @@
+import { throttle } from 'es-toolkit';
+import { LayoutRectangle, NativeScrollEvent } from 'react-native';
+
+export interface Root {
+  /**
+   * NodeHandle of the target component
+   */
+  node: any;
+  /**
+   * Whether horizontal scroll is enabled
+   */
+  horizontal: boolean;
+  /**
+   * Scroll event of the target component
+   */
+  current: NativeScrollEvent;
+  onLayout?: () => void;
+  onScroll?: (event: NativeScrollEvent) => void;
+}
+
+export interface Element {
+  inView: boolean;
+  intersectionRatio: number;
+  layout: LayoutRectangle;
+  measureLayout: (node: any, callback: (x: number, y: number, width: number, height: number) => void) => void;
+  onLayout?: () => void;
+}
+
+export interface IntersectionObserverEntry {
+  target: Element;
+  isIntersecting: boolean;
+  intersectionRatio: number;
+}
+
+export interface RootMargin {
+  left?: number;
+  right?: number;
+  top?: number;
+  bottom?: number;
+}
+
+export interface IntersectionObserverOptions {
+  /**
+   * Information about the component that wraps the element
+   */
+  root: Root;
+  rootMargin?: RootMargin;
+  threshold?: number | number[];
+}
+
+export type IntersectionObserverCallback = (entries: IntersectionObserverEntry[]) => void;
+
+export const defaultRootMargin: RootMargin = {
+  left: 0,
+  right: 0,
+  top: 0,
+  bottom: 0,
+};
+
+export const defaultThreshold = 0;
+
+/**
+ * @kind class
+ * @name IntersectionObserver
+ * @description
+ * IntersectionObserver implemented for React Native environment.
+ *
+ * @param {IntersectionObserverCallback} callback - Callback function that is called when the visibility state of the target element changes.
+ * @param {IntersectionObserverOptions} options - Options object that controls the behavior of IntersectionObserver.
+ */
+class IntersectionObserver {
+  protected callback: IntersectionObserverCallback;
+  protected options: IntersectionObserverOptions;
+  protected targets: Element[];
+
+  constructor(callback: IntersectionObserverCallback, options: IntersectionObserverOptions) {
+    this.callback = callback;
+    this.options = options;
+    this.targets = [];
+    this.options.root.onLayout = this.handleLayout;
+    this.options.root.onScroll = this.handleScroll;
+  }
+
+  protected measureTarget = (target: Element) => {
+    const rootNode = this.options.root.node;
+    if (rootNode) {
+      target.measureLayout(rootNode, (x, y, width, height) => {
+        target.layout = {
+          x,
+          y,
+          width,
+          height,
+        };
+        this.handleScroll();
+      });
+    }
+  };
+
+  protected handleLayout = throttle(
+    () => {
+      for (let index = 0; index < this.targets.length; index += 1) {
+        const target = this.targets[index];
+
+        if (target != null) {
+          this.measureTarget(target);
+        }
+      }
+    },
+    300,
+    { edges: ['trailing'] }
+  ) as () => void;
+
+  protected handleScroll = throttle(
+    () => {
+      const rootMargin = this.options?.rootMargin || defaultRootMargin;
+
+      const {
+        horizontal,
+        current: { contentOffset, contentSize, layoutMeasurement },
+      } = this.options.root;
+      if (
+        contentSize.width <= 0 ||
+        contentSize.height <= 0 ||
+        layoutMeasurement.width <= 0 ||
+        layoutMeasurement.height <= 0
+      ) {
+        return;
+      }
+      const contentOffsetWithLayout = horizontal
+        ? contentOffset.x + layoutMeasurement.width
+        : contentOffset.y + layoutMeasurement.height;
+      const changedTargets: IntersectionObserverEntry[] = [];
+      for (let index = 0; index < this.targets.length; index += 1) {
+        const target = this.targets[index];
+
+        if (target == null) {
+          continue;
+        }
+
+        const targetLayout = target.layout;
+        if (!targetLayout || targetLayout.width === 0 || targetLayout.height === 0) {
+          continue;
+        }
+
+        const previousIntersectionRatio = target.intersectionRatio;
+
+        let isIntersecting = false;
+        let intersectionRatio = previousIntersectionRatio;
+
+        if (horizontal) {
+          const visibleTargetMinX = Math.max(contentOffset.x - (rootMargin.left || 0), targetLayout.x);
+          const visibleTargetMaxX = Math.min(
+            contentOffsetWithLayout + (rootMargin.left || 0),
+            targetLayout.x + targetLayout.width
+          );
+          const visibleHeight = Math.max(visibleTargetMaxX - visibleTargetMinX, 0);
+
+          intersectionRatio = visibleHeight / targetLayout.height;
+          isIntersecting =
+            contentOffsetWithLayout + (rootMargin.right || 0) >= targetLayout.x &&
+            contentOffset.x - (rootMargin.left || 0) <= targetLayout.x + targetLayout.width;
+        } else {
+          const visibleTargetMinY = Math.max(contentOffset.y - (rootMargin.top || 0), targetLayout.y);
+          const visibleTargetMaxY = Math.min(
+            contentOffsetWithLayout + (rootMargin.bottom || 0),
+            targetLayout.y + targetLayout.height
+          );
+          const visibleHeight = Math.max(visibleTargetMaxY - visibleTargetMinY, 0);
+
+          intersectionRatio = visibleHeight / targetLayout.height;
+          isIntersecting =
+            contentOffsetWithLayout + (rootMargin.bottom || 0) >= targetLayout.y &&
+            contentOffset.y - (rootMargin.top || 0) <= targetLayout.y + targetLayout.height;
+        }
+
+        intersectionRatio = Math.floor(intersectionRatio * 100) / 100;
+
+        if (target.inView !== isIntersecting || target.intersectionRatio !== intersectionRatio) {
+          target.inView = isIntersecting;
+          target.intersectionRatio = intersectionRatio;
+
+          changedTargets.push({
+            target,
+            isIntersecting,
+            intersectionRatio,
+          });
+        }
+      }
+      this.callback(changedTargets);
+    },
+    100,
+    { edges: ['trailing'] }
+  ) as () => void;
+
+  public observe(target: Element) {
+    const index = this.targets.indexOf(target);
+    if (index < 0) {
+      target.onLayout = this.handleLayout;
+      this.targets.push(target);
+    }
+  }
+
+  public unobserve(target: Element) {
+    const index = this.targets.indexOf(target);
+    if (index >= 0) {
+      target.onLayout = undefined;
+      this.targets.splice(index, 1);
+    }
+  }
+}
+
+export default IntersectionObserver;

package/src/intersection-observer/index.ts

@@ -0,0 +1,24 @@
+import IOContext from './IOContext';
+import IOFlatList, { type IOFlatListController, type IOFlatListProps } from './IOFlatList';
+import IOScrollView, { type IOScrollViewController, type IOScrollViewProps } from './IOScrollView';
+import InView, { type InViewProps } from './InView';
+import {
+  type IntersectionObserverEntry,
+  type IntersectionObserverOptions,
+  type RootMargin,
+} from './IntersectionObserver';
+import type { IOComponentProps } from './withIO';
+
+export type {
+  IntersectionObserverEntry,
+  IntersectionObserverOptions,
+  RootMargin,
+  InViewProps,
+  IOComponentProps,
+  IOFlatListController,
+  IOFlatListProps,
+  IOScrollViewController,
+  IOScrollViewProps,
+};
+
+export { InView, IOContext, IOFlatList, IOScrollView };