create-pixi-vn 2.0.15 → 2.1.0

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/narration-hooks.ts

@@ -0,0 +1,255 @@
+import { SKIP_DELAY } from "@/constants";
+import { useGameProps } from "@/lib/hooks/props-hooks";
+import { AutoSettings } from "@/lib/stores/auto-settings-store";
+import { GameStatus } from "@/lib/stores/game-status-store";
+import { SearchParams } from "@/lib/stores/search-param-store";
+import { SkipSettings } from "@/lib/stores/skip-settings-store";
+import { TextDisplaySettings } from "@/lib/stores/text-display-settings-store";
+import { hasScrollableParent, isScrollableElement } from "@/lib/utils/scroll-utils";
+import { narration, stepHistory, type StoredIndexedChoiceInterface } from "@drincs/pixi-vn";
+import { useDebouncer } from "@tanstack/react-pacer";
+import { useSelector } from "@tanstack/react-store";
+import type React from "react";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+
+export function useNarrationFunctions() {
+    const gameProps = useGameProps();
+    const searchParams = useSelector(SearchParams.store, (state) => state);
+    const hasOpenMenu = useMemo(
+        () => Object.values(searchParams).some((value) => value !== undefined),
+        [searchParams],
+    );
+
+    const goNext = useCallback(async () => {
+        if (hasOpenMenu) return;
+        TextDisplaySettings.resetForNext();
+        GameStatus.setLoading(true);
+        try {
+            if (!narration.canContinue) {
+                GameStatus.setLoading(false);
+                return;
+            }
+            return narration
+                .continue(gameProps)
+                .then(() => {
+                    gameProps.invalidateInterfaceData();
+                    GameStatus.setLoading(false);
+                })
+                .catch((e) => {
+                    GameStatus.setLoading(false);
+                    console.error(e);
+                });
+        } catch (e) {
+            GameStatus.setLoading(false);
+            console.error(e);
+            return;
+        }
+    }, [gameProps, hasOpenMenu]);
+
+    const goBack = useCallback(async () => {
+        if (hasOpenMenu) return;
+        GameStatus.setLoading(true);
+        return stepHistory
+            .back(gameProps)
+            .then(() => {
+                GameStatus.setLoading(false);
+                gameProps.invalidateInterfaceData();
+            })
+            .catch((e) => {
+                GameStatus.setLoading(false);
+                console.error(e);
+            });
+    }, [gameProps, hasOpenMenu]);
+
+    const selectChoice = useCallback(
+        async (item: StoredIndexedChoiceInterface) => {
+            if (hasOpenMenu) return;
+            GameStatus.setLoading(true);
+            return narration
+                .selectChoice(item, gameProps)
+                .then(() => {
+                    gameProps.invalidateInterfaceData();
+                    GameStatus.setLoading(false);
+                })
+                .catch((e) => {
+                    GameStatus.setLoading(false);
+                    console.error(e);
+                });
+        },
+        [gameProps, hasOpenMenu],
+    );
+
+    return {
+        goNext,
+        goBack,
+        selectChoice,
+    };
+}
+
+/** Maximum pointer displacement (px) between pointerdown and pointerup that is still considered a tap/click. */
+const DRAG_THRESHOLD_PX = 5;
+const LONG_PRESS_SKIP_DELAY_MS = 700;
+const isDragGesture = (dx: number, dy: number) =>
+    dx * dx + dy * dy > DRAG_THRESHOLD_PX * DRAG_THRESHOLD_PX;
+
+export function useNarrationPointerHandlers() {
+    const { goNext } = useNarrationFunctions();
+    const skipEnabled = useSelector(SkipSettings.store, (state) => state.enabled);
+    const typewriterInProgress = useSelector(TextDisplaySettings.store, (state) => state.inProgress);
+    const pointerDownPos = useRef<{ x: number; y: number } | null>(null);
+    const longPressTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+    const longPressTriggered = useRef(false);
+
+    const clearLongPressTimer = useCallback(() => {
+        if (!longPressTimer.current) return;
+        clearTimeout(longPressTimer.current);
+        longPressTimer.current = null;
+    }, []);
+
+    const handlePointerDown = useCallback(
+        (e: React.PointerEvent) => {
+            if (e.button !== 0) return;
+            if (hasScrollableParent(e.target)) return;
+
+            longPressTriggered.current = false;
+            pointerDownPos.current = { x: e.clientX, y: e.clientY };
+            clearLongPressTimer();
+            longPressTimer.current = setTimeout(() => {
+                if (!pointerDownPos.current) return;
+                longPressTriggered.current = true;
+                SkipSettings.setEnabled(true);
+            }, LONG_PRESS_SKIP_DELAY_MS);
+        },
+        [clearLongPressTimer],
+    );
+
+    /**
+     * Clear the pending gesture on cancel.
+     * react-resizable-panels calls setPointerCapture() on the separator element in its
+     * pointermove handler (NOT in pointerdown), so the overlay never receives a native
+     * pointercancel when the separator takes over the drag. This handler ensures the ref
+     * is cleaned up in the cases where the browser itself cancels the gesture.
+     */
+    const handlePointerCancel = useCallback(() => {
+        clearLongPressTimer();
+        pointerDownPos.current = null;
+        if (longPressTriggered.current) {
+            SkipSettings.setEnabled(false);
+            longPressTriggered.current = false;
+        }
+    }, [clearLongPressTimer]);
+
+    const handlePointerUp = useCallback(
+        (e: React.PointerEvent) => {
+            // Only fire if a matching pointerdown was recorded on this element.
+            // If pointerdown started on a higher-z element (e.g. a resize handle),
+            // the ref will be null and we must not advance the narration.
+            if (!pointerDownPos.current) return;
+
+            const dx = e.clientX - pointerDownPos.current.x;
+            const dy = e.clientY - pointerDownPos.current.y;
+            clearLongPressTimer();
+            pointerDownPos.current = null;
+
+            // If the pointer moved significantly it was a drag (e.g. resize), not a tap.
+            if (isDragGesture(dx, dy)) return;
+
+            // Let resize handles manage their own drag behaviour
+            if ((e.target as HTMLElement).closest('[data-slot="resizable-handle"]')) return;
+            // Let native scrollbar interactions through
+            if (isScrollableElement(e.target as HTMLElement)) return;
+
+            if (longPressTriggered.current) {
+                SkipSettings.setEnabled(false);
+                longPressTriggered.current = false;
+                return;
+            }
+
+            if (skipEnabled) {
+                SkipSettings.setEnabled(false);
+            }
+            if (typewriterInProgress && !narration.dialogGlue) {
+                TextDisplaySettings.complete();
+                return;
+            }
+            goNext();
+        },
+        [clearLongPressTimer, goNext, skipEnabled, typewriterInProgress],
+    );
+
+    const handlePointerMove = useCallback(
+        (e: React.PointerEvent) => {
+            if (!pointerDownPos.current) return;
+            const dx = e.clientX - pointerDownPos.current.x;
+            const dy = e.clientY - pointerDownPos.current.y;
+            if (!isDragGesture(dx, dy)) return;
+            clearLongPressTimer();
+            pointerDownPos.current = null;
+            if (longPressTriggered.current) {
+                SkipSettings.setEnabled(false);
+                longPressTriggered.current = false;
+            }
+        },
+        [clearLongPressTimer],
+    );
+
+    useEffect(
+        () => () => {
+            clearLongPressTimer();
+        },
+        [clearLongPressTimer],
+    );
+
+    return { handlePointerDown, handlePointerCancel, handlePointerMove, handlePointerUp };
+}
+
+export function useSkipAutoDetector() {
+    const skipEnabled = useSelector(SkipSettings.store, (state) => state.enabled);
+    const autoEnabled = useSelector(AutoSettings.store, (state) => state.enabled);
+    const autoTime = useSelector(AutoSettings.store, (state) => state.time);
+    const typewriterInProgress = useSelector(
+        TextDisplaySettings.store,
+        (state) => state.inProgress,
+    );
+    const searchParams = useSelector(SearchParams.store, (state) => state);
+    const hasOpenMenu = useMemo(
+        () => Object.values(searchParams).some((value) => value !== undefined),
+        [searchParams],
+    );
+    const { goNext } = useNarrationFunctions();
+
+    const savedGoNext = useRef(goNext);
+    useEffect(() => {
+        savedGoNext.current = goNext;
+    }, [goNext]);
+    useEffect(() => {
+        if (skipEnabled && !hasOpenMenu) {
+            const id = setInterval(() => savedGoNext.current(), SKIP_DELAY);
+            return () => clearInterval(id);
+        }
+    }, [skipEnabled, hasOpenMenu]);
+
+    const autoDebouncer = useDebouncer(
+        (_trigger: {
+            autoEnabled: boolean;
+            skipEnabled: boolean;
+            typewriterInProgress: boolean;
+            autoTime: number;
+            hasOpenMenu: boolean;
+        }) => {
+            goNext();
+        },
+        {
+            wait: autoTime * 1000,
+            enabled: autoEnabled && !skipEnabled && !typewriterInProgress && !hasOpenMenu,
+        },
+    );
+
+    const { maybeExecute } = autoDebouncer;
+
+    useEffect(() => {
+        maybeExecute({ autoEnabled, skipEnabled, typewriterInProgress, autoTime, hasOpenMenu });
+    }, [maybeExecute, autoEnabled, skipEnabled, typewriterInProgress, autoTime, hasOpenMenu]);
+
+    return null;
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/navigation-hooks.ts

@@ -0,0 +1,112 @@
+import { SearchParams } from "@/lib/stores/search-param-store";
+import { useLocation, useNavigate } from "@tanstack/react-router";
+import { useSelector } from "@tanstack/react-store";
+import { useCallback, useEffect } from "react";
+
+// Shared pending param changes — all synchronous setters accumulate here
+// and a single navigate fires after a very short delay.
+const _pendingParams: Record<string, unknown> = {};
+let _pendingTimer: ReturnType<typeof setTimeout> | null = null;
+let _pendingNavigate: ((...args: unknown[]) => unknown) | null = null;
+
+function scheduleNavigate(navigate: (...args: unknown[]) => unknown, key: string, value: unknown) {
+    _pendingParams[key] = value;
+    _pendingNavigate = navigate;
+    if (_pendingTimer !== null) {
+        clearTimeout(_pendingTimer);
+    }
+    _pendingTimer = setTimeout(() => {
+        _pendingTimer = null;
+        if (_pendingNavigate) {
+            const snapshot = { ..._pendingParams };
+            for (const k of Object.keys(_pendingParams)) {
+                delete _pendingParams[k];
+            }
+            _pendingNavigate({
+                search: (prev: Record<string, unknown>) => ({ ...prev, ...snapshot }),
+            });
+            _pendingNavigate = null;
+        }
+    }, 10);
+}
+
+/**
+ * useConfirmBackNavigation
+ *
+ * Prevent accidental browser "back" navigation.
+ * Behavior:
+ * - On each `href` change it pushes a history state (`pushState`).
+ * - Listens for `popstate` and calls `history.forward()` to cancel a single
+ *   press of the browser back button.
+ * - If the user presses back twice in succession (i.e. the second press occurs
+ *   before the first is handled), the browser will navigate back.
+ *
+ * Usage: call this hook at the app root to avoid unintended back navigations
+ * (e.g. accidental taps or gestures). Returns `null`.
+ */
+export function useConfirmBackNavigation() {
+    const { href } = useLocation();
+
+    useEffect(() => {
+        const isInIframe = typeof window !== "undefined" && window.self !== window.top;
+        if (isInIframe) return;
+        const listener = () => {
+            window.history.forward();
+        };
+        window.addEventListener("popstate", listener);
+
+        return () => {
+            window.removeEventListener("popstate", listener);
+        };
+    }, []);
+
+    useEffect(() => {
+        window.history.pushState(null, href, href);
+    }, [href]);
+
+    return null;
+}
+
+/**
+ * Returns the current value of the given URL search param from the internal store.
+ *
+ * @param field - The search param key to read.
+ * @returns The current value, or `undefined` if not set.
+ */
+export function useSearchParamState<T>(field: string): T | undefined {
+    const storeValue = useSelector(SearchParams.store, (state) => state[field]) as T | undefined;
+    return storeValue;
+}
+
+/**
+ * Returns a stable setter for the given URL search param.
+ *
+ * Calling the setter instantly updates the internal store (so components
+ * re-render without waiting for the URL update) and then debounces the
+ * `navigate()` call to avoid flooding the browser history on rapid changes.
+ *
+ * Pass `undefined` to remove the param from the URL.
+ *
+ * @param field - The search param key to write.
+ * @returns A stable callback that accepts either a value or an updater function.
+ */
+export function useSetSearchParamState<T>(
+    field: string,
+): (value: T | undefined | ((previous: T | undefined) => T | undefined)) => void {
+    const navigate = useNavigate();
+
+    return useCallback(
+        (value) => {
+            const currentValue = SearchParams.store.state[field] as T | undefined;
+            const nextValue =
+                typeof value === "function"
+                    ? (value as (previous: T | undefined) => T | undefined)(currentValue)
+                    : value;
+            const normalizedValue = nextValue === false ? undefined : nextValue;
+
+            SearchParams.set(field, normalizedValue);
+            scheduleNavigate(navigate as never, field, normalizedValue);
+        },
+        [field, navigate],
+    );
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/network-hooks.ts

@@ -0,0 +1,34 @@
+import { useCallback, useEffect, useState } from "react";
+
+type NetworkStatus = {
+    isOnline: boolean;
+    retry: () => void;
+};
+
+export function useNetworkDetector(): NetworkStatus {
+    const [isOnline, setIsOnline] = useState(() => navigator.onLine);
+
+    const checkOnline = useCallback(() => {
+        setIsOnline(navigator.onLine);
+    }, []);
+
+    useEffect(() => {
+        const handleVisibility = () => {
+            if (!document.hidden) {
+                checkOnline();
+            }
+        };
+
+        window.addEventListener("online", checkOnline);
+        window.addEventListener("offline", checkOnline);
+        document.addEventListener("visibilitychange", handleVisibility);
+
+        return () => {
+            window.removeEventListener("online", checkOnline);
+            window.removeEventListener("offline", checkOnline);
+            document.removeEventListener("visibilitychange", handleVisibility);
+        };
+    }, [checkOnline]);
+
+    return { isOnline, retry: checkOnline };
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/nqtr-hooks.ts

@@ -0,0 +1,121 @@
+import { CANVAS_UI_LAYER_NAME, INTERFACE_DATA_USE_QUERY_KEY } from "@/constants";
+import { useGameProps } from "@/lib/hooks/props-hooks";
+import { useQueryCurrentMap } from "@/lib/query/map-query";
+import { useQueryCurrentRoom } from "@/lib/query/room-query";
+import { GameStatus } from "@/lib/stores/game-status-store";
+import { navigator, questsNotebook, routine, timeTracker, type OnRunProps } from "@drincs/nqtr";
+import { canvas, storage } from "@drincs/pixi-vn";
+import { useQueryClient } from "@tanstack/react-query";
+import { useCallback, useEffect, useRef } from "react";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+export function useMapLayerSync() {
+    const { data: { background, locations } = {} } = useQueryCurrentMap();
+
+    useEffect(() => {
+        const layer = canvas.getLayer(CANVAS_UI_LAYER_NAME);
+        if (layer) {
+            if (background) layer.addChild(background);
+            locations?.forEach((location) => {
+                layer.addChild(location);
+            });
+        }
+
+        return () => {
+            canvas.getLayer(CANVAS_UI_LAYER_NAME)?.removeChildren();
+        };
+    }, [background, locations]);
+
+    return null;
+}
+
+export function useRoomLayerSync() {
+    const {
+        data: {
+            room: { automaticFunctions = [], id } = {},
+            background,
+            activities,
+            routine: routineIcons,
+        } = {},
+    } = useQueryCurrentRoom();
+    const gameProps = useGameProps();
+    const autoRunning = useRef(false);
+
+    useEffect(() => {
+        if (!id || id !== navigator.currentRoomId) return;
+
+        const layer = canvas.getLayer(CANVAS_UI_LAYER_NAME);
+        if (layer) {
+            if (background) layer.addChild(background);
+
+            activities?.forEach((icon) => {
+                layer.addChild(icon);
+            });
+            routineIcons?.forEach((icon) => {
+                layer.addChild(icon);
+            });
+        }
+
+        if (automaticFunctions.length > 0 && !autoRunning.current) {
+            autoRunning.current = true;
+            const automaticFunction = automaticFunctions[0];
+            GameStatus.setLoading(true);
+            automaticFunction(gameProps).finally(() => {
+                GameStatus.setLoading(false);
+                autoRunning.current = false;
+            });
+        }
+
+        return () => {
+            canvas.getLayer(CANVAS_UI_LAYER_NAME)?.removeChildren();
+        };
+    }, [id, background, automaticFunctions, gameProps, activities, routineIcons]);
+
+    return null;
+}
+
+const NOT_CAN_SPEND_TIME_FLAG_KEY = "not_can_spend_time";
+export default function useTimeTracker() {
+    const { t } = useTranslation(["ui"]);
+    const queryClient = useQueryClient();
+
+    const sleep = useCallback(
+        (newDayHour: number, props: OnRunProps) => {
+            if (storage.getFlag(NOT_CAN_SPEND_TIME_FLAG_KEY)) {
+                toast(t("cant_sleep_now"));
+                return false;
+            }
+            timeTracker.increaseDate(1, newDayHour);
+            routine.clearExpiredRoutine();
+            navigator.clearExpiredActivities();
+            questsNotebook.startsStageMustBeStarted(props);
+            return true;
+        },
+        [t],
+    );
+
+    const wait = useCallback(
+        (timeSpent: number) => {
+            if (storage.getFlag(NOT_CAN_SPEND_TIME_FLAG_KEY)) {
+                toast(t("cant_sleep_now"));
+                return false;
+            }
+            if (timeTracker.currentTime + timeSpent >= 23 || timeTracker.currentTime < 5) {
+                toast(t("cant_wait_now"));
+                return false;
+            }
+            timeTracker.increaseTime(timeSpent);
+            queryClient.invalidateQueries({
+                queryKey: [INTERFACE_DATA_USE_QUERY_KEY],
+            });
+            return true;
+        },
+        [t, queryClient],
+    );
+
+    return {
+        sleep,
+        wait,
+    };
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/pause-game-hooks.ts

@@ -0,0 +1,53 @@
+import { SearchParams } from "@/lib/stores/search-param-store";
+import { canvas, sound } from "@drincs/pixi-vn";
+import { useSelector } from "@tanstack/react-store";
+import { useEffect, useMemo, useRef } from "react";
+
+function pauseGameFromMenuOpen() {
+    sound.pauseUnsavedAll();
+    canvas.pause();
+}
+
+function resumeGameFromMenuClose() {
+    sound.resumeUnsavedAll();
+    canvas.resume();
+}
+
+/**
+ * Pauses the game when at least one search param is active.
+ * Resumes the game once all menu-related search params are closed.
+ *
+ * Must be called from a component that is only rendered on the `/game` route
+ * so that pause/resume is automatically scoped to the game screen.
+ */
+export function usePauseGameWhenMenuIsOpen() {
+    const searchParams = useSelector(SearchParams.store, (state) => state);
+    const pausedByMenuRef = useRef(false);
+
+    const hasOpenMenu = useMemo(
+        () => Object.values(searchParams).some((value) => value !== undefined),
+        [searchParams],
+    );
+
+    useEffect(() => {
+        if (hasOpenMenu && !pausedByMenuRef.current) {
+            pauseGameFromMenuOpen();
+            pausedByMenuRef.current = true;
+            return;
+        }
+
+        if (!hasOpenMenu && pausedByMenuRef.current) {
+            resumeGameFromMenuClose();
+            pausedByMenuRef.current = false;
+        }
+    }, [hasOpenMenu]);
+
+    useEffect(() => {
+        return () => {
+            if (pausedByMenuRef.current) {
+                resumeGameFromMenuClose();
+                pausedByMenuRef.current = false;
+            }
+        };
+    }, []);
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/props-hooks.ts

@@ -0,0 +1,30 @@
+import { INTERFACE_DATA_USE_QUERY_KEY } from "@/constants";
+import useTimeTracker from "@/lib/hooks/nqtr-hooks";
+import type { StepLabelProps } from "@drincs/pixi-vn";
+import { useQueryClient } from "@tanstack/react-query";
+import { useNavigate } from "@tanstack/react-router";
+import { useTranslation } from "react-i18next";
+import { toast } from "sonner";
+
+export function useGameProps(): StepLabelProps {
+    const navigate = useNavigate();
+    const { t } = useTranslation(["narration"]);
+    const { t: uiTransition } = useTranslation(["ui"]);
+    const queryClient = useQueryClient();
+    const { sleep, wait } = useTimeTracker();
+
+    return {
+        navigate,
+        t,
+        uiTransition,
+        toast,
+        invalidateInterfaceData: async (delay: number = 0) => {
+            if (delay > 0) await new Promise((resolve) => setTimeout(resolve, delay));
+            return await queryClient.invalidateQueries({
+                queryKey: [INTERFACE_DATA_USE_QUERY_KEY],
+            });
+        },
+        sleep,
+        wait,
+    };
+}

package/template-nqtr-react-vite-muijoy-tauri/src/lib/hooks/quick-tools-hooks.ts

@@ -0,0 +1,80 @@
+import { HTML_CANVAS_LAYER_NAME, HTML_UI_LAYER_NAME } from "@/constants";
+import { useGameProps } from "@/lib/hooks/props-hooks";
+import { GameStatus } from "@/lib/stores/game-status-store";
+import { hasScrollableParent } from "@/lib/utils/scroll-utils";
+import { type StepLabelProps, stepHistory } from "@drincs/pixi-vn";
+import { narration } from "@drincs/pixi-vn/narration";
+import { useThrottler } from "@tanstack/react-pacer";
+import { useEffect, useRef } from "react";
+
+function isInsideRoot(target: EventTarget | null, selector: string): boolean {
+    if (!(target instanceof HTMLElement)) return false;
+    return target.closest(`#${selector}`) !== null;
+}
+
+export function useWheelActions({
+    throttleMs = 300,
+    minDelta = 20,
+}: {
+    throttleMs?: number;
+    minDelta?: number;
+} = {}) {
+    const pendingAsync = useRef(0);
+    const gameProps = useGameProps();
+
+    const runAsync = async (fn: (props: StepLabelProps) => Promise<unknown>) => {
+        try {
+            pendingAsync.current += 1;
+            GameStatus.setLoading(pendingAsync.current > 0);
+            await fn(gameProps);
+        } finally {
+            pendingAsync.current -= 1;
+            GameStatus.setLoading(pendingAsync.current > 0);
+            if (pendingAsync.current === 0) {
+                gameProps.invalidateInterfaceData();
+            }
+        }
+    };
+
+    const handleWheel = useThrottler(
+        async (event: WheelEvent) => {
+            if (
+                !(
+                    isInsideRoot(event.target, HTML_UI_LAYER_NAME) ||
+                    isInsideRoot(event.target, HTML_CANVAS_LAYER_NAME)
+                )
+            )
+                return;
+            if (hasScrollableParent(event.target)) return;
+
+            // blocca lo scroll nativo
+            event.preventDefault();
+
+            const { deltaY } = event;
+
+            // ignora micro-movimenti del trackpad
+            if (Math.abs(deltaY) < minDelta) return;
+
+            if (deltaY < 0) {
+                // ⬆️ Scroll up
+                await runAsync(narration.continue.bind(narration));
+            }
+
+            if (deltaY > 0) {
+                // ⬇️ Scroll down
+                await runAsync(stepHistory.back.bind(stepHistory));
+            }
+        },
+        { wait: throttleMs },
+    );
+
+    useEffect(() => {
+        window.addEventListener("wheel", handleWheel.maybeExecute, { passive: false });
+
+        return () => {
+            window.removeEventListener("wheel", handleWheel.maybeExecute);
+        };
+    }, [handleWheel.maybeExecute]);
+
+    return null;
+}