@seed-design/stackflow 0.0.0-alpha-20260414104312

package/src/primitive/AppScreen/useAppScreenContext.ts

@@ -0,0 +1,21 @@
+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,188 @@
+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" | "canceling" | "completing";
+
+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((prev) => (prev === "swiping" ? prev : "swiping"));
+          onSwipeStart?.();
+        },
+        [onSwipeStart],
+      );
+
+      const moveSwipeBack = useCallback(
+        ({ x, t }: MoveSwipeBackProps) => {
+          const displacement = Math.max(0, x - swipeBackContextRef.current.x0);
+          const displacementRatio = displacement / window.innerWidth;
+          const velocity = displacement / (t - swipeBackContextRef.current.t0);
+          setSwipeBackContext({
+            ...swipeBackContextRef.current,
+            displacement,
+            displacementRatio,
+            velocity,
+          });
+          setSwipeBackState((prev) => (prev === "swiping" ? prev : "swiping"));
+          onSwipeMove?.({ displacement, displacementRatio });
+        },
+        [onSwipeMove],
+      );
+
+      const endSwipeBack = useCallback(
+        (_: EndSwipeBackProps) => {
+          const swiped =
+            swipeBackContextRef.current.displacementRatio > displacementRatioThreshold ||
+            swipeBackContextRef.current.velocity > velocityThreshold;
+
+          if (swiped) {
+            stackRef.current?.style.setProperty("--swipe-back-target", "100%");
+            setSwipeBackState("completing");
+          } else {
+            stackRef.current?.style.setProperty("--swipe-back-target", "0");
+            setSwipeBackState("canceling");
+          }
+
+          onSwipeEnd?.({ swiped });
+        },
+        [onSwipeEnd, displacementRatioThreshold, velocityThreshold],
+      );
+
+      const reset = useCallback(() => {
+        setSwipeBackContext({
+          x0: 0,
+          t0: 0,
+          displacement: 0,
+          displacementRatio: 0,
+          velocity: 0,
+        });
+        stackRef.current?.style.setProperty("--swipe-back-target", "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,
+      "data-top-transition-style": topActivity.transitionStyle,
+    }),
+    [
+      swipeBackState,
+      topActivity.transitionState,
+      topActivity.activityType,
+      topActivity.transitionStyle,
+    ],
+  ) 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: {
+        onAnimationEnd: (e) => {
+          if (e.target === e.currentTarget) {
+            events.reset();
+          }
+        },
+        onTransitionEnd: (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.ts

@@ -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,33 @@
+import { useStack } from "@stackflow/react";
+import { useLayoutEffect, 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"];
+  const transitionStyle = topEl?.dataset["transitionStyle"];
+
+  useLayoutEffect(() => {
+    if (!topId) return;
+
+    const el = document.querySelector<HTMLElement>(`[data-activity-id="${topId}"]`);
+    setTopEl(el);
+  }, [topId]);
+
+  return {
+    transitionState,
+    activityType,
+    transitionStyle,
+  };
+}

package/src/utils/createStyleContext.tsx

@@ -0,0 +1,128 @@
+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;
+  };
+}

package/src/utils/styled.ts

@@ -0,0 +1,41 @@
+import type { ScopedColorBg, ScopedColorPalette, ScopedColorBanner } from "@seed-design/css/vars";
+import { vars } from "@seed-design/css/vars";
+
+/**
+ * A minimal subset of `StyleProps` from `@seed-design/react`.
+ * Copied here to avoid package dependency. May be extracted to a shared package later.
+ */
+export interface BoxBackgroundProps {
+  /**
+   * Shorthand for `background`.
+   */
+  bg?: ScopedColorBg | ScopedColorPalette | ScopedColorBanner | (string & {});
+
+  background?: ScopedColorBg | ScopedColorPalette | ScopedColorBanner | (string & {});
+}
+
+function handleColor(color: string | undefined) {
+  if (!color) {
+    return undefined;
+  }
+  const [type, value] = color.split(".");
+
+  // @ts-expect-error - dynamic access
+  return vars.$color[type]?.[value] ?? color;
+}
+
+export function useBoxBackgroundProps<T extends BoxBackgroundProps>(
+  props: T,
+): {
+  style: React.CSSProperties;
+  restProps: Omit<T, keyof BoxBackgroundProps>;
+} {
+  const { bg, background, ...restProps } = props;
+
+  return {
+    style: {
+      "--seed-box-background": handleColor(background ?? bg),
+    } as React.CSSProperties,
+    restProps: restProps as Omit<T, keyof BoxBackgroundProps>,
+  };
+}