@seed-design/stackflow 0.0.1-alpha-20250210081704

package/src/primitive/AppScreen/AppScreen.tsx

@@ -0,0 +1,66 @@
+import { mergeProps } from "@seed-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
+import { forwardRef } from "react";
+import { useAppScreen, type UseAppScreenProps } from "./useAppScreen";
+import { AppScreenProvider, useAppScreenContext } from "./useAppScreenContext";
+
+export interface AppScreenRootProps
+  extends PrimitiveProps,
+    UseAppScreenProps,
+    React.HTMLAttributes<HTMLDivElement> {}
+
+export const AppScreenRoot = forwardRef<HTMLDivElement, AppScreenRootProps>((props, ref) => {
+  const {
+    swipeBackDisplacementRatioThreshold,
+    swipeBackVelocityThreshold,
+    onSwipeBackEnd,
+    onSwipeBackMove,
+    onSwipeBackStart,
+    ...otherProps
+  } = props;
+  const api = useAppScreen({
+    swipeBackDisplacementRatioThreshold,
+    swipeBackVelocityThreshold,
+    onSwipeBackEnd,
+    onSwipeBackMove,
+    onSwipeBackStart,
+  });
+
+  return (
+    <AppScreenProvider value={api}>
+      <Primitive.div
+        ref={ref}
+        data-stackflow-component-name="AppScreen"
+        {...mergeProps(api.activityProps, otherProps)}
+      />
+    </AppScreenProvider>
+  );
+});
+AppScreenRoot.displayName = "AppScreenRoot";
+
+export interface AppScreenDimProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const AppScreenDim = forwardRef<HTMLDivElement, AppScreenDimProps>((props, ref) => {
+  const { dimProps } = useAppScreenContext();
+
+  return <Primitive.div ref={ref} {...mergeProps(dimProps, props)} />;
+});
+AppScreenDim.displayName = "AppScreenDim";
+
+export interface AppScreenEdgeProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const AppScreenEdge = forwardRef<HTMLDivElement, AppScreenEdgeProps>((props, ref) => {
+  const { edgeProps } = useAppScreenContext();
+
+  return <Primitive.div ref={ref} {...mergeProps(edgeProps, props)} />;
+});
+AppScreenEdge.displayName = "AppScreenEdge";
+
+export interface AppScreenLayerProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const AppScreenLayer = forwardRef<HTMLDivElement, AppScreenLayerProps>((props, ref) => {
+  const { layerProps } = useAppScreenContext();
+
+  return <Primitive.div ref={ref} {...mergeProps(layerProps, props)} />;
+});
+AppScreenLayer.displayName = "AppScreenLayer";

package/src/primitive/AppScreen/index.ts

@@ -0,0 +1,13 @@
+export {
+  AppScreenDim,
+  AppScreenEdge,
+  AppScreenLayer,
+  AppScreenRoot,
+  type AppScreenDimProps,
+  type AppScreenEdgeProps,
+  type AppScreenLayerProps,
+  type AppScreenRootProps,
+} from "./AppScreen";
+
+export * as AppScreen from "./AppScreen.namespace";
+export { useAppScreenContext, type UseAppScreenContext } from "./useAppScreenContext";

package/src/primitive/AppScreen/useAppScreen.tsx

@@ -0,0 +1,68 @@
+import { dataAttr, elementProps } from "@seed-design/dom-utils";
+import { useNullableActivity, useZIndexBase } from "@stackflow/react-ui-core";
+import { useMemo } from "react";
+import { type UseSwipeBackProps, useSwipeBack } from "../GlobalInteraction/useSwipeBack";
+
+export interface UseAppScreenProps extends UseSwipeBackProps {}
+
+export type UseAppScreenReturn = ReturnType<typeof useAppScreen>;
+
+export function useAppScreen(props: UseAppScreenProps) {
+  const activity = useNullableActivity();
+
+  const transitionState = activity?.transitionState ?? "enter-done";
+
+  const { activityProps, layerProps, edgeProps } = useSwipeBack(props);
+
+  const zIndexBase = useZIndexBase();
+  const zIndexStyle = useMemo(
+    () =>
+      ({
+        "--z-index-base": zIndexBase.toString(),
+      }) as React.CSSProperties,
+    [zIndexBase],
+  );
+
+  const stateProps = useMemo(
+    () => ({
+      "data-activity-is-top": dataAttr(activity?.isTop),
+      "data-activity-is-active": dataAttr(activity?.isActive),
+      "data-transition-state": transitionState,
+    }),
+    [transitionState, activity?.isActive, activity?.isTop],
+  ) as React.HTMLAttributes<HTMLElement>;
+
+  return useMemo(
+    () => ({
+      activity,
+      stateProps,
+      activityProps: elementProps({
+        "data-part": "activity",
+        "data-activity-type": "full-screen",
+        ...activityProps,
+        ...stateProps,
+        "data-activity-id": activity?.id,
+        style: zIndexStyle,
+        // FIXME: @stackflow/react should prevent activity.id hydration mismatch; this is temporal fix.
+        suppressHydrationWarning: true,
+      }),
+      dimProps: elementProps({
+        "data-part": "dim",
+        ...stateProps,
+      }),
+      layerProps: elementProps({
+        "data-part": "layer",
+        ...stateProps,
+        ...layerProps,
+      }),
+      edgeProps: elementProps({
+        "data-part": "edge",
+        "aria-hidden": true,
+        tabIndex: -1,
+        ...edgeProps,
+        ...stateProps,
+      }),
+    }),
+    [activity, zIndexStyle, stateProps, activityProps, edgeProps, layerProps],
+  );
+}

package/src/primitive/AppScreen/useAppScreenContext.ts

@@ -0,0 +1,19 @@
+import { createContext, useContext } from "react";
+import type { UseAppScreenReturn } from "./useAppScreen";
+
+export interface UseAppScreenContext extends UseAppScreenReturn {}
+
+const AppScreenContext = createContext<UseAppScreenContext | null>(null);
+
+export const AppScreenProvider = AppScreenContext.Provider;
+
+export function useAppScreenContext<T extends boolean | undefined = true>({
+  strict = true,
+}: { strict?: T } = {}): T extends false ? UseAppScreenContext | null : UseAppScreenContext {
+  const context = useContext(AppScreenContext);
+  if (!context && strict) {
+    throw new Error("useAppScreenContext must be used within a AppScreen");
+  }
+
+  return context as UseAppScreenContext;
+}

package/src/primitive/GlobalInteraction/GlobalInteraction.tsx

@@ -0,0 +1,25 @@
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { mergeProps } from "@seed-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
+import { forwardRef } from "react";
+import { useGlobalInteraction } from "./useGlobalInteraction";
+import { GlobalInteractionProvider } from "./useGlobalInteractionContext";
+
+export interface GlobalInteractionProps
+  extends PrimitiveProps,
+    React.HTMLAttributes<HTMLDivElement> {}
+
+export const GlobalInteraction = forwardRef<HTMLDivElement, GlobalInteractionProps>(
+  (props, ref) => {
+    const api = useGlobalInteraction();
+    return (
+      <GlobalInteractionProvider value={api}>
+        <Primitive.div
+          ref={composeRefs(api.stackRef, ref)}
+          {...mergeProps(api.stackProps, props)}
+        />
+      </GlobalInteractionProvider>
+    );
+  },
+);
+GlobalInteraction.displayName = "GlobalInteraction";

package/src/primitive/GlobalInteraction/index.ts

@@ -0,0 +1,6 @@
+export { GlobalInteraction, type GlobalInteractionProps } from "./GlobalInteraction";
+
+export {
+  useGlobalInteractionContext,
+  type UseGlobalInteractionContext,
+} from "./useGlobalInteractionContext";

package/src/primitive/GlobalInteraction/useGlobalInteraction.ts

@@ -0,0 +1,178 @@
+import { useCallbackRef } from "@radix-ui/react-use-callback-ref";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useTopActivity } from "../private/useTopActivity";
+
+export type SwipeBackState = "idle" | "swiping" | "transitioning";
+
+export type UseGlobalInteractionReturn = ReturnType<typeof useGlobalInteraction>;
+
+export interface SwipeBackContext {
+  x0: number;
+  t0: number;
+  displacement: number;
+  displacementRatio: number;
+  velocity: number;
+}
+
+export interface SwipeBackProps {
+  /**
+   * The threshold to determine whether the swipe back is intentional.
+   * @default 0.4
+   */
+  swipeBackDisplacementRatioThreshold?: number;
+
+  /**
+   * The threshold to determine whether the swipe back is intentional.
+   * @default 1
+   */
+  swipeBackVelocityThreshold?: number;
+
+  onSwipeBackStart?: () => void;
+  onSwipeBackMove?: (props: { displacement: number; displacementRatio: number }) => void;
+  onSwipeBackEnd?: (props: { swiped: boolean }) => void;
+}
+
+export interface StartSwipeBackProps {
+  x0: number;
+  t0: number;
+}
+
+export interface MoveSwipeBackProps {
+  x: number;
+  t: number;
+}
+
+// biome-ignore lint/suspicious/noEmptyInterface: intentionally empty for future extension
+export interface EndSwipeBackProps {}
+
+export function useGlobalInteraction() {
+  const [swipeBackState, setSwipeBackState] = useState<SwipeBackState>("idle");
+
+  const swipeBackContextRef = useRef<SwipeBackContext>({
+    x0: 0,
+    t0: 0,
+    displacement: 0,
+    displacementRatio: 0,
+    velocity: 0,
+  });
+  const stackRef = useRef<HTMLDivElement>(null);
+
+  const setSwipeBackContext = useCallback((ctx: SwipeBackContext) => {
+    swipeBackContextRef.current = ctx;
+    stackRef.current?.style.setProperty(
+      "--swipe-back-displacement",
+      `${ctx.displacement.toString()}px`,
+    );
+    stackRef.current?.style.setProperty(
+      "--swipe-back-displacement-ratio",
+      ctx.displacementRatio.toString(),
+    );
+  }, []);
+
+  const getSwipeBackEvents = useCallback(
+    (props: SwipeBackProps) => {
+      const {
+        swipeBackDisplacementRatioThreshold: displacementRatioThreshold = 0.4,
+        swipeBackVelocityThreshold: velocityThreshold = 1,
+      } = props;
+      const onSwipeStart = useCallbackRef(props.onSwipeBackStart);
+      const onSwipeMove = useCallbackRef(props.onSwipeBackMove);
+      const onSwipeEnd = useCallbackRef(props.onSwipeBackEnd);
+
+      const startSwipeBack = useCallback(
+        ({ x0, t0 }: StartSwipeBackProps) => {
+          setSwipeBackContext({
+            x0,
+            t0,
+            displacement: 0,
+            displacementRatio: 0,
+            velocity: 0,
+          });
+          setSwipeBackState("swiping");
+
+          onSwipeStart?.();
+        },
+        [onSwipeStart],
+      );
+
+      const moveSwipeBack = useCallback(
+        ({ x, t }: MoveSwipeBackProps) => {
+          const displacement = x - swipeBackContextRef.current.x0;
+          const displacementRatio = displacement / window.innerWidth;
+          const velocity = displacement / (t - swipeBackContextRef.current.t0);
+          setSwipeBackContext({
+            ...swipeBackContextRef.current,
+            displacement,
+            displacementRatio,
+            velocity,
+          });
+          setSwipeBackState("swiping");
+
+          onSwipeMove?.({ displacement, displacementRatio });
+        },
+        [onSwipeMove],
+      );
+
+      const endSwipeBack = useCallback(
+        (_: EndSwipeBackProps) => {
+          const swiped =
+            swipeBackContextRef.current.displacementRatio > displacementRatioThreshold ||
+            swipeBackContextRef.current.velocity > velocityThreshold;
+
+          // we intentionally do not reset context here, so that the displacement can be used for exit animation
+          setSwipeBackState("transitioning");
+
+          onSwipeEnd?.({ swiped });
+        },
+        [onSwipeEnd, displacementRatioThreshold, velocityThreshold],
+      );
+
+      const reset = useCallback(() => {
+        setSwipeBackContext({
+          x0: 0,
+          t0: 0,
+          displacement: 0,
+          displacementRatio: 0,
+          velocity: 0,
+        });
+        setSwipeBackState("idle");
+      }, []);
+
+      return useMemo(
+        () => ({
+          startSwipeBack,
+          moveSwipeBack,
+          endSwipeBack,
+          reset,
+        }),
+        [startSwipeBack, moveSwipeBack, endSwipeBack, reset],
+      );
+    },
+    [setSwipeBackContext],
+  );
+
+  const topActivity = useTopActivity();
+
+  const stackProps = useMemo(
+    () => ({
+      "data-swipe-back-state": swipeBackState,
+      "data-global-transition-state": topActivity.transitionState,
+      "data-top-activity-type": topActivity.activityType,
+    }),
+    [swipeBackState, topActivity.transitionState, topActivity.activityType],
+  ) as React.HTMLAttributes<HTMLElement>;
+
+  return useMemo(
+    () => ({
+      stackRef,
+      swipeBackContextRef,
+      swipeBackState,
+      setSwipeBackState,
+      setSwipeBackContext,
+      getSwipeBackEvents,
+
+      stackProps,
+    }),
+    [swipeBackState, setSwipeBackContext, getSwipeBackEvents, stackProps],
+  );
+}

package/src/primitive/GlobalInteraction/useGlobalInteractionContext.tsx

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+import type { UseGlobalInteractionReturn } from "./useGlobalInteraction";
+
+export interface UseGlobalInteractionContext extends UseGlobalInteractionReturn {}
+
+const GlobalInteractionContext = createContext<UseGlobalInteractionContext | null>(null);
+
+export const GlobalInteractionProvider = GlobalInteractionContext.Provider;
+
+export function useGlobalInteractionContext<T extends boolean | undefined = true>({
+  strict = true,
+}: { strict?: T } = {}): T extends false
+  ? UseGlobalInteractionContext | null
+  : UseGlobalInteractionContext {
+  const context = useContext(GlobalInteractionContext);
+  if (!context && strict) {
+    throw new Error("useGlobalInteractionContext must be used within a GlobalInteractionProvider");
+  }
+
+  return context as UseGlobalInteractionContext;
+}

package/src/primitive/GlobalInteraction/useSwipeBack.ts

@@ -0,0 +1,56 @@
+import { useEffect, useMemo } from "react";
+import type { SwipeBackProps } from "./useGlobalInteraction";
+import { useGlobalInteractionContext } from "./useGlobalInteractionContext";
+
+export interface UseSwipeBackProps extends SwipeBackProps {}
+
+export function useSwipeBack(props: UseSwipeBackProps) {
+  const globalInteraction = useGlobalInteractionContext();
+  const events = globalInteraction.getSwipeBackEvents(props);
+
+  useEffect(() => {
+    return () => {
+      events.reset();
+    };
+  }, [events]);
+
+  return useMemo(
+    () => ({
+      activityProps: {
+        "data-swipe-back": "",
+      } as React.HTMLAttributes<HTMLDivElement>,
+      layerProps: {
+        onTransitionEnd: (e) => {
+          if (e.target === e.currentTarget) {
+            events.reset();
+          }
+        },
+        onAnimationEnd: (e) => {
+          if (e.target === e.currentTarget) {
+            events.reset();
+          }
+        },
+      } as React.HTMLAttributes<HTMLDivElement>,
+      edgeProps: {
+        tabIndex: -1,
+        onTouchStart: (e) => {
+          const x0 = e.touches[0].clientX;
+          const t0 = Date.now();
+          events.startSwipeBack({ x0, t0 });
+        },
+        onTouchMove: (e) => {
+          const x = e.touches[0].clientX;
+          const t = Date.now();
+          events.moveSwipeBack({ x, t });
+        },
+        onTouchEnd: () => {
+          events.endSwipeBack({});
+        },
+        onTouchCancel: () => {
+          events.endSwipeBack({});
+        },
+      } as React.HTMLAttributes<HTMLElement>,
+    }),
+    [events],
+  );
+}

package/src/primitive/index.tsx

@@ -0,0 +1,3 @@
+export * from "./AppScreen";
+export * from "./AppBar";
+export * from "./GlobalInteraction";

package/src/primitive/private/useElementOffset.ts

@@ -0,0 +1,37 @@
+import * as React from "react";
+
+const useLayoutEffect = typeof window !== "undefined" ? React.useLayoutEffect : React.useEffect;
+
+export function useElementOffset(element: HTMLElement | null) {
+  const [offset, setOffset] = React.useState<{ fromLeft: number; fromRight: number } | undefined>(
+    undefined,
+  );
+
+  useLayoutEffect(() => {
+    if (!element) {
+      setOffset(undefined);
+      return;
+    }
+
+    if (element) {
+      // provide as early as possible
+      setOffset({
+        fromLeft: element.offsetLeft + element.offsetWidth,
+        fromRight: (element.offsetParent ?? document.body).clientWidth - element.offsetLeft,
+      });
+
+      const resizeObserver = new ResizeObserver(() => {
+        const fromLeft = element.offsetLeft + element.offsetWidth;
+        const fromRight = (element.offsetParent ?? document.body).clientWidth - element.offsetLeft;
+
+        setOffset({ fromLeft, fromRight });
+      });
+
+      resizeObserver.observe(element);
+
+      return () => resizeObserver.unobserve(element);
+    }
+  }, [element]);
+
+  return offset;
+}

package/src/primitive/private/useTopActivity.ts

@@ -0,0 +1,31 @@
+import { useStack } from "@stackflow/react";
+import { useEffect, useState } from "react";
+
+export function useTopActivity() {
+  const stack = useStack();
+  if (!stack) {
+    throw new Error(
+      "useStack is not available in the context. Make sure you are using @stackflow/react >= 1.4.1. (https://github.com/daangn/stackflow/blob/main/integrations/react/CHANGELOG.md#141)",
+    );
+  }
+
+  const topId = stack.activities.find((activity) => activity.isTop)?.id;
+  const topActivity = stack.activities.find((activity) => activity.isTop);
+  const transitionState = topActivity?.transitionState ?? "enter-done";
+
+  // TODO: There should be a better way to handle this. We should not rely on the DOM element to get the activity type.
+  const [topEl, setTopEl] = useState<HTMLElement | null>(null);
+  const activityType = topEl?.dataset["activityType"];
+
+  useEffect(() => {
+    if (!topId) return;
+
+    const el = document.querySelector<HTMLElement>(`[data-activity-id="${topId}"]`);
+    setTopEl(el);
+  }, [topId]);
+
+  return {
+    transitionState,
+    activityType,
+  };
+}

package/src/utils/createStyleContext.tsx

@@ -0,0 +1,125 @@
+import clsx from "clsx";
+import { createContext, forwardRef, useContext } from "react";
+
+type Recipe<
+  Props extends Record<string, string | boolean | undefined>,
+  Classnames extends Record<string, string>,
+> = ((props?: Props) => Classnames) & {
+  splitVariantProps: <T extends Props>(props: T) => [Props, Omit<T, keyof Props>];
+};
+
+export function createStyleContext<
+  Props extends Record<string, string | boolean | undefined>,
+  Classnames extends Record<string, string>,
+>(recipe: Recipe<Props, Classnames>) {
+  const ClassNamesContext = createContext<Classnames | null>(null);
+  const PropsContext = createContext<Props | null>(null);
+
+  const ClassNamesProvider = ({
+    children,
+    value,
+  }: { children: React.ReactNode; value: Classnames }) => {
+    return <ClassNamesContext.Provider value={value}>{children}</ClassNamesContext.Provider>;
+  };
+
+  const PropsProvider = ({ children, value }: { children: React.ReactNode; value: Props }) => {
+    return <PropsContext.Provider value={value}>{children}</PropsContext.Provider>;
+  };
+
+  function useClassNames() {
+    const context = useContext(ClassNamesContext);
+    if (context === null) {
+      throw new Error(
+        "useClassNames must be used within a ClassNamesProvider. Did you forget to wrap your component in a ClassNamesProvider?",
+      );
+    }
+
+    return context;
+  }
+
+  function useProps() {
+    return useContext(PropsContext);
+  }
+
+  const withRootProvider = <P,>(
+    Component: React.ElementType<any>,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P>> => {
+    const { defaultProps } = options ?? {};
+
+    const StyledComponent = (innerProps: any) => {
+      const props = { ...(defaultProps ?? {}), ...useProps(), ...innerProps } as Props &
+        React.HTMLAttributes<HTMLElement>;
+      const [variantProps, otherProps] = recipe.splitVariantProps(props);
+      const classNames = recipe(variantProps); // TODO: should we memoize this?
+
+      return (
+        <ClassNamesProvider value={classNames}>
+          <Component {...otherProps} />
+        </ClassNamesProvider>
+      );
+    };
+
+    // @ts-ignore
+    StyledComponent.displayName = Component.displayName || Component.name;
+
+    return StyledComponent as any;
+  };
+
+  const withProvider = <T, P>(
+    Component: React.ElementType<any>,
+    slot: keyof Classnames,
+    options?: {
+      defaultProps?: Partial<P>;
+    },
+  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>> => {
+    const { defaultProps } = options ?? {};
+
+    const StyledComponent = forwardRef<any, any>((innerProps, ref) => {
+      const props = { ...(defaultProps ?? {}), ...useProps(), ...innerProps } as Props &
+        React.HTMLAttributes<HTMLElement>;
+      const [variantProps, otherProps] = recipe.splitVariantProps(props);
+      const classNames = recipe(variantProps); // TODO: should we memoize this?
+      const className = classNames[slot as keyof typeof classNames];
+
+      return (
+        <ClassNamesProvider value={classNames}>
+          <Component ref={ref} {...otherProps} className={clsx(className, props.className)} />
+        </ClassNamesProvider>
+      );
+    });
+
+    // @ts-ignore
+    StyledComponent.displayName = Component.displayName || Component.name;
+
+    return StyledComponent as any;
+  };
+
+  const withContext = <T, P>(
+    Component: React.ElementType<any>,
+    slot?: keyof Classnames,
+  ): React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<T>> => {
+    const StyledComponent = forwardRef<any, React.HTMLAttributes<HTMLElement>>((props, ref) => {
+      const classNames = useClassNames();
+      const className = classNames?.[slot as keyof typeof classNames];
+
+      return <Component ref={ref} {...props} className={clsx(className, props.className)} />;
+    });
+
+    // @ts-ignore
+    StyledComponent.displayName = Component.displayName || Component.name;
+    return StyledComponent as any;
+  };
+
+  return {
+    ClassNamesProvider,
+    PropsProvider,
+    useClassNames,
+    useProps,
+    withRootProvider,
+    withProvider,
+    withContext,
+  };
+}

package/src/utils/createWithStateProps.tsx

@@ -0,0 +1,28 @@
+import { forwardRef } from "react";
+
+type AtLeastOne<T> = [T, ...T[]];
+
+export function createWithStateProps(
+  useContexts: AtLeastOne<
+    (prop?: { strict?: boolean }) => { stateProps: React.HTMLAttributes<HTMLElement> } | null
+  >,
+  options?: { strict?: boolean },
+) {
+  const strict = options?.strict ?? true;
+
+  return function withStateProps<P, R>(Component: React.ComponentType<P & React.RefAttributes<R>>) {
+    const Node = forwardRef<R, P>((props, ref) => {
+      const stateProps = {};
+      for (const useContext of useContexts) {
+        Object.assign(stateProps, useContext({ strict })?.stateProps);
+      }
+
+      // @ts-ignore
+      return <Component ref={ref} {...stateProps} {...props} />;
+    });
+
+    Node.displayName = Component.displayName || Component.name;
+
+    return Node;
+  };
+}