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

package/src/event/abstract.ts

@@ -0,0 +1,130 @@
+export abstract class GraniteEventDefinition<O = undefined, R = void> {
+  // Event name (literal type recommended)
+  abstract name: string;
+
+  /**
+   * Method to implement event logic.
+   * @param options - Event options (undefined if not used)
+   * @param onEvent - Callback called when the event is triggered.
+   * @param onError - Callback called on error (error type: unknown)
+   */
+  abstract listener(options: O, onEvent: (response: R) => void, onError: (error: unknown) => void): void;
+
+  /**
+   * Additional logic to execute when removing the event listener.
+   * If needed in the plugin, override this method and it will be called
+   * when the listener is removed.
+   */
+  abstract remove(): void;
+}
+
+/**
+ * GraniteEvent class registers event definition instances passed to the constructor.
+ * The addEventListener method only allows registered event names, and the types of passed
+ * options/callbacks are automatically inferred.
+ *
+ * Each subscription is uniquely identified by (event name + options).
+ */
+export class GraniteEvent<Defs extends GraniteEventDefinition<unknown, unknown>> {
+  private definitions = new Map<Defs['name'], Defs>();
+  private subscriptionGroups = new Map<
+    string,
+    {
+      eventName: Defs['name'];
+      options: Extract<Defs, { name: Defs['name'] }> extends GraniteEventDefinition<infer O, any> ? O : never;
+      callbacks: Array<{
+        onEvent: (response: any) => void;
+        onError?: (error: unknown) => void;
+      }>;
+    }
+  >();
+
+  constructor(defs: Defs[]) {
+    for (const def of defs) {
+      this.definitions.set(def.name, def);
+    }
+  }
+
+  addEventListener<E extends Defs['name']>(
+    eventName: E,
+    listener: Extract<Defs, { name: E }> extends GraniteEventDefinition<infer O, infer R>
+      ? [O] extends [undefined]
+        ? { onEvent: (response: R) => void; onError?: (error: unknown) => void }
+        : { options: O; onEvent: (response: R) => void; onError?: (error: unknown) => void }
+      : never
+  ): () => void {
+    const def = this.definitions.get(eventName);
+    if (!def) {
+      throw new Error(`Event "${String(eventName)}" is not registered.`);
+    }
+    const opts = (listener as any).options;
+    const key = this._getKey(String(eventName), opts);
+    let group = this.subscriptionGroups.get(key);
+
+    if (!group) {
+      group = {
+        eventName,
+        options: opts,
+        callbacks: [],
+      };
+      this.subscriptionGroups.set(key, group);
+
+      const aggregatedOnEvent = (response: any) => {
+        for (const cb of group!.callbacks) {
+          cb.onEvent(response);
+        }
+      };
+      const aggregatedOnError = (error: unknown) => {
+        for (const cb of group!.callbacks) {
+          if (cb.onError) {
+            cb.onError(error);
+          }
+        }
+      };
+
+      def.listener(group.options, aggregatedOnEvent, aggregatedOnError);
+    }
+
+    group.callbacks.push({ onEvent: listener.onEvent, onError: listener.onError });
+
+    return () => {
+      const grp = this.subscriptionGroups.get(key);
+      if (!grp) {
+        return;
+      }
+      grp.callbacks = grp.callbacks.filter((cb) => cb.onEvent !== listener.onEvent);
+      if (grp.callbacks.length === 0) {
+        def.remove();
+        this.subscriptionGroups.delete(key);
+      }
+    };
+  }
+
+  emit<E extends Defs['name']>(
+    eventName: E,
+    data: Extract<Defs, { name: E }> extends GraniteEventDefinition<unknown, infer R> ? R : never
+  ) {
+    const def = this.definitions.get(eventName);
+    if (!def) {
+      throw new Error(`Event "${String(eventName)}" is not registered.`);
+    }
+
+    for (const group of this.subscriptionGroups.values()) {
+      if (group.eventName === eventName) {
+        for (const callback of group.callbacks) {
+          try {
+            callback.onEvent(data);
+          } catch (error) {
+            if (callback.onError) {
+              callback.onError(error);
+            }
+          }
+        }
+      }
+    }
+  }
+
+  private _getKey(eventName: string, options: unknown): string {
+    return `${eventName}:${options ? JSON.stringify(options) : ''}`;
+  }
+}

package/src/event/index.ts

@@ -0,0 +1,2 @@
+export * from './abstract';
+export * from './useGraniteEvent';

package/src/event/useGraniteEvent.ts

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+import { GraniteEvent, GraniteEventDefinition } from './abstract';
+import { BackEventControls, useBackEvent } from '../use-back-event/useBackEvent';
+
+class BackEvent extends GraniteEventDefinition<void, void> {
+  name = 'backEvent' as const;
+
+  ref = {
+    remove: () => {},
+  };
+
+  constructor(private backEventControls: BackEventControls) {
+    super();
+  }
+
+  remove() {
+    this.ref.remove();
+  }
+
+  listener(_: void, onEvent: (response: void) => void): void {
+    this.backEventControls.addEventListener(onEvent);
+    this.ref.remove = () => this.backEventControls.removeEventListener(onEvent);
+  }
+}
+
+export function useGraniteEvent() {
+  const backEvent = useBackEvent();
+
+  const event = useMemo(() => {
+    return new GraniteEvent([new BackEvent(backEvent)]);
+  }, [backEvent]);
+
+  return event;
+}

package/src/impression-area/ImpressionArea.tsx

@@ -0,0 +1,341 @@
+import { debounce } from 'es-toolkit';
+import { PropsWithChildren, ReactElement, ReactNode, useContext, useEffect, useMemo, useState } from 'react';
+import { StyleProp, View, ViewStyle } from 'react-native';
+import { InView, IOContext } from '../intersection-observer';
+import { noop } from '../utils/noop';
+import { usePreservedCallback } from '../utils/usePreservedCallback';
+import { useVisibility } from '../visibility';
+
+interface Props {
+  onImpressionStart?: () => void;
+  onImpressionEnd?: () => void;
+  enabled?: boolean;
+  UNSAFE__impressFallbackOnMount?: boolean;
+  style?: StyleProp<ViewStyle>;
+  areaThreshold?: number;
+  timeThreshold?: number;
+  children?: ReactNode;
+}
+
+/**
+ * @public
+ * @category Screen Control
+ * @name ImpressionArea
+ * @description
+ * A component that detects whether a specific component is visible on the screen and notifies the outside. Using this component, you can easily implement features like collecting logs or running animations when a specific component becomes visible on the screen.
+ * The visibility is detected using the return value of `useVisibility` and the `IOScrollView` and `InView` components that indicate whether the component is displayed within the viewport. When using `ScrollView` in React, even if a view is not visible on the screen, using `ImpressionArea` allows you to trigger events only when the view is actually visible on the screen.
+
+::: info Note
+
+`ImpressionArea` must be used inside `IOScrollView`. If you need to use it outside of `IOScrollView`, you can set the `UNSAFE__impressFallbackOnMount` property to `true` to detect based on when the component is mounted. If this property is set to `false` and used outside of `IOScrollView`, an `IOProviderMissingError` will occur.
+
+:::
+ *
+ * @param {() => void} [onImpressionStart] Callback function that is executed when the child component becomes visible on the screen.
+ * @param {() => void} [onImpressionEnd] Callback function that is executed when the child component is hidden from the screen.
+ * @param {boolean} [enabled=true] Value that directly controls the condition for visibility. Default value is `true`. If passed as `false`, the `onImpressionStart` callback function will not be executed even if the component is visible.
+ * @param {number} [areaThreshold=0] Value that sets the ratio of the visible area. If the component appears on the screen with a ratio greater than this value, `onImpressionStart` is called.
+ * The value should be set between 0 and 1. Setting it to 0 triggers the event when even 1px of the component is visible. Conversely, setting it to 1 only triggers the event when the component is 100% visible on the screen.
+ * @param {number} [timeThreshold=0] Sets the time in milliseconds before `onImpressionStart` is called after this component becomes visible on the screen. Default value is `0` milliseconds (0 seconds).
+ * @param {ViewStyle} [style] `style` value to be applied to the `InView` component. Default value is `undefined`, used when you want to specify a style.
+ * @param {boolean} [UNSAFE__impressFallbackOnMount=false] Whether to consider the component as visible immediately when mounted. Default value is `false`.
+ * Useful when you cannot determine if the component is in the viewport without using `IOScrollView`. For example, a component located outside of `IOScrollView` will be considered visible at mount time if set to `true`.
+ *
+ * @returns {ReactElement} - Returns a component that can detect visibility on the screen.
+ * @example
+ * 
+ * ### Basic Usage Example
+ * 
+ * ```tsx
+ * import { useState } from 'react';
+ * import { Button, Dimensions, Text, View } from 'react-native';
+ * import { ImpressionArea, IOScrollView } from '@granite-js/react-native';
+ * 
+ * export default function ImpressionAreaExample() {
+ *  const [isImpressionStart, setIsImpressionStart] = useState(false);
+ * 
+ *  return (
+ *    <>
+ *      <Text>{isImpressionStart ? 'Impression Start' : 'Impression End'}</Text>
+ *        <IOScrollView
+ *          style={{
+ *            flex: 1,
+ *            margin: 16,
+ *            backgroundColor: 'white',
+ *          }}
+ *        >
+ *        <View
+ *          style={{
+ *            height: Dimensions.get('screen').height,
+ *            borderWidth: 1,
+ *            borderColor: 'black',
+ *          }}
+ *        >
+ *          <Text>Scroll to here</Text>
+ *        </View>
+ * 
+ *        <ImpressionArea
+ *          onImpressionStart={() => setIsImpressionStart(true)}
+ *          onImpressionEnd={() => setIsImpressionStart(false)}
+ *        >
+ *          <Button title="Button" />
+ *        </ImpressionArea>
+ *      </IOScrollView>
+ *    </>
+ *  );
+ * }
+ * ```
+ *
+ * ### Example of Detection at Mount Time
+ * 
+ * When `ImpressionArea` is not located inside a component like `IOScrollView`, setting `UNSAFE__impressFallbackOnMount` to `true` will consider the component as visible when it is mounted.
+ * 
+ * ```tsx
+ * import { useState } from 'react';
+ * import { Button, Dimensions, ScrollView, Text, View } from 'react-native';
+ * import { ImpressionArea } from '@granite-js/react-native';
+ * 
+ * export default function ImpressionArea2Example() {
+ *  const [isImpressionStart, setIsImpressionStart] = useState(false);
+ * 
+ *  return (
+ *    <>
+ *      <Text>{isImpressionStart ? 'Impression Start' : 'Impression End'}</Text>
+ *      <ScrollView
+ *        style={{
+ *          flex: 1,
+ *          margin: 16,
+ *          backgroundColor: 'white',
+ *        }}
+ *      >
+ *        <View
+ *          style={{
+ *            height: Dimensions.get('screen').height,
+ *            borderWidth: 1,
+ *            borderColor: 'black',
+ *          }}
+ *        >
+ *          <Text>Scroll to here</Text>
+ *        </View>
+ * 
+ *        <ImpressionArea
+ *          UNSAFE__impressFallbackOnMount={true}
+ *          onImpressionStart={() => setIsImpressionStart(true)}
+ *          onImpressionEnd={() => setIsImpressionStart(false)}
+ *        >
+ *          <Button title="Button" />
+ *        </ImpressionArea>
+ *      </ScrollView>
+ *    </>
+ *  );
+ * }
+ * ```
+ */
+export function ImpressionArea(props: Props): ReactElement {
+  const context = useContext(IOContext);
+
+  if (context?.manager == null && props.UNSAFE__impressFallbackOnMount) {
+    return <ImpressionAreaOnMount {...props} />;
+  }
+
+  return <ImpressionAreaWithIntersectionObserver {...props} />;
+}
+
+export class IOProviderMissingError extends Error {
+  message =
+    'ImpressionArea가 IOContext.Provider 밖에서 사용되었습니다. ' +
+    '최상위 ScrollView가 @granite-js/react-native의 IOScrollView인지 확인해주세요.';
+}
+
+/**
+ * @category Components
+ * @kind function
+ * @name ImpressionAreaOnMount
+ * @description
+ * A component that calls `onImpressionStart` and `onImpressionEnd` when the component is mounted on the screen.
+ * Used when `UNSAFE__impressFallbackOnMount` is `true` in `ImpressionArea`.
+ * This component can be used when `ImpressionArea` is needed outside of `IOScrollView`.
+ *
+ * @param {() => void} [onImpressionStart] - Callback function that is called when the component is mounted.
+ * @param {() => void} [onImpressionEnd] - Callback function that is called when the component is unmounted.
+ * @param {StyleProp<ViewStyle>} [style] - Sets the style of the top-level container of the `ImpressionAreaOnMount` component.
+ * @param {ReactNode} [children] - Sets the child components to be wrapped by `ImpressionAreaOnMount`.
+ * @returns {ReactElement} - Returns a component that detects mount status
+ * @example
+ * ### Example of Detection at Mount Time
+ * ```tsx
+ * import { ImpressionAreaOnMount } from '@granite-js/react-native';
+ *
+ * export default function AlwaysImpressionAreaPage() {
+ *   // isImpressionStart is set to true when AlwaysImpressionAreaPage is mounted
+ *   const [isImpressionStart, setIsImpressionStart] = useState(false);
+ *
+ *   return (
+ *     <ScrollView
+ *       style={{
+ *         flex: 1,
+ *         padding: 16,
+ *         backgroundColor: 'white',
+ *       }}
+ *     >
+ *       <TestTitle title="ImpressionArea" description="@granite-js/impression-area" />
+ *       <Button label={'Scroll to origin'} onPress={() => {}} />
+ *       <Code style={{ width, height }} json={{ isImpressionStart }} />
+ *       <ImpressionAreaOnMount
+ *         onImpressionStart={() => setIsImpressionStart(true)}
+ *         onImpressionEnd={() => setIsImpressionStart(false)}
+ *       >
+ *         <Button label={'Scroll to here'} onPress={() => {}} />
+ *       </ImpressionArea>
+ *     </ScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function ImpressionAreaOnMount({
+  onImpressionStart: _onImpressionStart = noop,
+  onImpressionEnd: _onImpressionEnd = noop,
+  style,
+  children,
+}: PropsWithChildren<Props>): ReactElement {
+  const visible = useVisibility();
+
+  const isImpressed = visible;
+
+  const onImpressionStart = usePreservedCallback(_onImpressionStart);
+  const onImpressionEnd = usePreservedCallback(_onImpressionEnd);
+
+  useEffect(() => {
+    if (isImpressed) {
+      onImpressionStart();
+    } else {
+      onImpressionEnd();
+    }
+  }, [isImpressed, onImpressionStart, onImpressionEnd]);
+
+  return <View style={style}>{children}</View>;
+}
+
+/**
+ * @category Components
+ * @kind function
+ * @name ImpressionAreaWithIntersectionObserver
+ * @description
+ * A component that calls `onImpressionStart` and `onImpressionEnd` based on whether the component is visible on the user's screen.
+ * This is a component that can be used in `IOScrollView` and can notify the outside about its visibility status.
+ *
+ * @param {() => void} [onImpressionStart] - Callback function that is called when the component becomes visible on the screen.
+ * @param {() => void} [onImpressionEnd] - Callback function that is called when the component disappears from the screen.
+ * @param {boolean} [enabled=true] - Sets whether to enable `ImpressionArea`.
+ * @param {StyleProp<ViewStyle>} [style] - Sets the style of the top-level container of the `ImpressionAreaWithIntersectionObserver` component.
+ * @param {number} [areaThreshold=0] - Considers the component visible when its visible area exceeds the set ratio.
+ * @param {number} [timeThreshold=0] - Sets the time in milliseconds before `onImpressionStart` and `onImpressionEnd` are called after the component becomes visible on the screen. Default value is `0` milliseconds.
+ * @param {ReactNode} [children] - Sets the child components to be wrapped by `ImpressionAreaWithIntersectionObserver`.
+ * @returns {ReactElement} - Returns a component that can detect visibility on the screen.
+ * @example
+ * ### Example using IntersectionObserver
+ * ```tsx
+ * import { ImpressionAreaWithIntersectionObserver, IOScrollView } from '@granite-js/react-native';
+ *
+ * export default function ImpressionAreaPage() {
+ *   const [isImpressionStart, setIsImpressionStart] = useState(false);
+ *
+ *   return (
+ *     <IOScrollView
+ *       style={{
+ *         flex: 1,
+ *         margin: 16,
+ *         backgroundColor: 'white',
+ *       }}
+ *     >
+ *       <TestTitle title="ImpressionArea" description="@granite-js/impression-area" />
+ *       <Button label={'Scroll to origin'} onPress={() => {}} />
+ *       <Code style={{ width, height }} textStyle={{ flex: 1, verticalAlign: 'middle' }} json={{ isImpressionStart }} />
+ *       <ImpressionAreaWithIntersectionObserver
+ *         onImpressionStart={() => setIsImpressionStart(true)}
+ *         onImpressionEnd={() => setIsImpressionStart(false)}
+ *       >
+ *         <Button label={'Scroll to here'} onPress={() => {}} />
+ *       </ImpressionArea>
+ *     </IOScrollView>
+ *   );
+ * }
+ * ```
+ */
+export function ImpressionAreaWithIntersectionObserver({
+  onImpressionStart: _onImpressionStart = noop,
+  onImpressionEnd: _onImpressionEnd = noop,
+  timeThreshold = 0,
+  ...props
+}: PropsWithChildren<{
+  onImpressionStart?: () => void;
+  onImpressionEnd?: () => void;
+  enabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  areaThreshold?: number;
+  timeThreshold?: number;
+}>): ReactElement {
+  const [isImpressed, setIsImpressed] = useState(false);
+
+  const onImpressionChange = useMemo(() => {
+    if (timeThreshold === 0) {
+      return setIsImpressed;
+    } else {
+      return debounce(setIsImpressed, timeThreshold);
+    }
+  }, [setIsImpressed, timeThreshold]);
+
+  const onImpressionStart = usePreservedCallback(_onImpressionStart);
+  const onImpressionEnd = usePreservedCallback(_onImpressionEnd);
+
+  useEffect(() => {
+    if (isImpressed) {
+      onImpressionStart?.();
+    } else {
+      onImpressionEnd?.();
+    }
+  }, [isImpressed, onImpressionStart, onImpressionEnd]);
+
+  return <ImpressionAreaImpl {...props} onImpressionChange={onImpressionChange} />;
+}
+
+function ImpressionAreaImpl({
+  children,
+  onImpressionChange: _onImpressionChange = noop,
+  enabled = true,
+  areaThreshold = 0,
+  style,
+}: PropsWithChildren<{
+  onImpressionChange?: (isImpressed: boolean) => void;
+  enabled?: boolean;
+  style?: StyleProp<ViewStyle>;
+  areaThreshold?: number;
+}>) {
+  const visible = useVisibility();
+  const [inviewImpressed, setInviewImpressed] = useState(false);
+
+  const context = useContext(IOContext);
+
+  if (context?.manager == null) {
+    throw new IOProviderMissingError();
+  }
+
+  const impressed = visible && inviewImpressed && enabled;
+  const onImpressionChange = usePreservedCallback(_onImpressionChange);
+
+  useEffect(() => {
+    onImpressionChange?.(impressed);
+  }, [impressed, onImpressionChange]);
+
+  return (
+    <InView
+      onChange={(inView, currentThreshold) => {
+        const isVisible = inView && currentThreshold >= areaThreshold;
+        setInviewImpressed(isVisible);
+      }}
+      style={style}
+    >
+      {children}
+    </InView>
+  );
+}

package/src/impression-area/index.ts

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

package/src/index.ts

@@ -0,0 +1,24 @@
+import './types/global';
+
+export { Granite } from './app';
+export * from '@granite-js/style-utils';
+export * from '@granite-js/image';
+export * from '@granite-js/lottie';
+
+export * from './dev-entrypoint';
+export * from './native-modules/natives';
+export * from './visibility';
+export * from './use-back-event';
+export * from './keyboard';
+export * from './intersection-observer';
+export * from './impression-area';
+export * from './scroll-view-inertial-background';
+export * from './react';
+export * from './router/createRoute';
+export * from './event';
+export * from './video';
+export * from './status-bar';
+export * from './blur';
+
+export type { InitialProps, ColorPreference } from './initial-props';
+export type { GraniteProps } from './app';

package/src/initial-props/InitialProps.ts

@@ -0,0 +1,95 @@
+/**
+ * @public
+ * @category UI
+ * @name ColorPreference
+ * @description
+ * Type representing the color mode of the current device. It is a string representing light mode and dark mode.
+ *
+ * @typedef {'light' | 'dark'} ColorPreference
+ */
+export type ColorPreference = 'light' | 'dark';
+
+/**
+ * @category Types
+ * @name BaseInitialProps
+ * @description
+ * Interface representing the base initial properties.
+ *
+ * @interface
+ * @property {'ios' | 'android'} platform - Platform type
+ * @property {ColorPreference} initialColorPreference - Initial color
+ * @property {string} [scheme] - Executed scheme
+ */
+type BaseInitialProps = {
+  platform: 'ios' | 'android';
+  initialColorPreference: ColorPreference;
+  scheme?: string;
+};
+
+/**
+ * @category Types
+ * @name AndroidInitialProps
+ * @description
+ * Values passed from Android to React Native.
+ *
+ * @interface
+ * @augments BaseInitialProps
+ * @property {'android'} platform - Platform name (Android)
+ */
+export type AndroidInitialProps = BaseInitialProps & {
+  platform: 'android';
+};
+
+/**
+ * @category Types
+ * @name IOSInitialProps
+ * @description
+ * Interface representing iOS initial properties.
+ *
+ * @interface
+ * @augments BaseInitialProps
+ * @property {'ios'} platform - Platform (iOS)
+ */
+export type IOSInitialProps = BaseInitialProps & {
+  platform: 'ios';
+};
+
+/**
+ * @public
+ * @category Core
+ * @name InitialProps
+ * @description
+ * Provides the initial data type that native platforms (Android/iOS) pass to the app when a user enters a specific screen in a React Native app.
+ * The initial data contains important information used for screen initialization, and the required data types differ by native platform.
+ *
+ * The data type provided by Android is `AndroidInitialProps`, and the data type provided by iOS is `IOSInitialProps`.
+ *
+ * @property {'ios' | 'android'} platform - The platform on which the app is currently running. Has a value of either `ios` or `android`.
+ * @property {ColorPreference} initialColorPreference - The initial color theme. Represents the color theme set by the user.
+ * @property {string} [scheme] - The URL scheme used to enter the current screen.
+ *
+ * @example
+ *
+ * ### Example using `InitialProps`
+ *
+ * ::: code-group
+ * ```tsx [_app.tsx]
+ * import { PropsWithChildren } from 'react';
+ * import { Granite, InitialProps } from '@granite-js/react-native';
+ * import { context } from '../require.context';
+ *
+ * const APP_NAME = 'my-app-name';
+ *
+ * function AppContainer({ children, ...initialProps }: PropsWithChildren<InitialProps>) {
+ *   console.log({ initialProps });
+ *   return <>{children}</>;
+ * }
+ *
+ * export default Granite.registerApp(AppContainer, {
+ *   appName: APP_NAME,
+ *   context,
+ * });
+ * ```
+ * :::
+ */
+export type InitialProps = AndroidInitialProps | IOSInitialProps;

package/src/initial-props/index.ts

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

package/src/intersection-observer/IOContext.ts

@@ -0,0 +1,16 @@
+import { createContext } from 'react';
+import IOManager from './IOManager';
+
+export interface IOContextValue {
+  manager: null | IOManager;
+}
+
+/**
+ * @name IOContext
+ * @description Context that shares the IOManager instance.
+ */
+const IOContext = createContext<IOContextValue>({
+  manager: null,
+});
+
+export default IOContext;