@babylonjs/shared-ui-components 9.2.0 → 9.2.2

package/modularTool/hooks/settingsHooks.js

@@ -0,0 +1,40 @@
+import { useCallback, useEffect, useMemo } from "react";
+import { Observable } from "@babylonjs/core/Misc/observable.js";
+import { useSettingsStore } from "../contexts/settingsContext.js";
+import { useObservableState } from "./observableHooks.js";
+/**
+ * Hook that reads and writes a setting from the settings store.
+ * @param descriptor The setting descriptor that identifies the setting and its default value.
+ * @returns A tuple of [currentValue, setValue, resetValue] similar to React's useState.
+ */
+export function useSetting(descriptor) {
+    const settingsStore = useSettingsStore();
+    // Only watch for this specific setting to change. Otherwise, any time any setting changes we would
+    // call readSetting again, which if it is an object, it will be a new instance, which can cause
+    // unnecessary re-renders in consumers of this hook.
+    const settingObservable = useMemo(() => new Observable(), []);
+    useEffect(() => {
+        if (settingsStore) {
+            const observer = settingsStore.onChanged.add((key) => {
+                if (key === descriptor.key) {
+                    settingObservable.notifyObservers();
+                }
+            });
+            return () => {
+                observer.remove();
+            };
+        }
+        return undefined;
+    }, [settingsStore, descriptor.key]);
+    const value = useObservableState(useCallback(() => settingsStore?.readSetting(descriptor) ?? descriptor.defaultValue, [settingsStore, descriptor.key, descriptor.defaultValue]), settingObservable);
+    const setValue = useCallback((newValue) => {
+        const value = typeof newValue === "function" ? newValue(settingsStore?.readSetting(descriptor) ?? descriptor.defaultValue) : newValue;
+        settingsStore?.writeSetting(descriptor, value);
+    }, [settingsStore, descriptor.key, descriptor.defaultValue]);
+    const resetValue = useCallback(() => settingsStore?.writeSetting(descriptor, descriptor.defaultValue), [settingsStore, descriptor.key, descriptor.defaultValue]);
+    if (!settingsStore) {
+        throw new Error("Settings store is not available in context.");
+    }
+    return [value, setValue, resetValue];
+}
+//# sourceMappingURL=settingsHooks.js.map

package/modularTool/hooks/settingsHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settingsHooks.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/hooks/settingsHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsC,WAAW,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAI5F,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAI,UAAgC;IAC1D,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IAEzC,mGAAmG;IACnG,+FAA+F;IAC/F,oDAAoD;IACpD,MAAM,iBAAiB,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,UAAU,EAAQ,EAAE,EAAE,CAAC,CAAC;IACpE,SAAS,CAAC,GAAG,EAAE;QACX,IAAI,aAAa,EAAE,CAAC;YAChB,MAAM,QAAQ,GAAG,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACjD,IAAI,GAAG,KAAK,UAAU,CAAC,GAAG,EAAE,CAAC;oBACzB,iBAAiB,CAAC,eAAe,EAAE,CAAC;gBACxC,CAAC;YACL,CAAC,CAAC,CAAC;YAEH,OAAO,GAAG,EAAE;gBACR,QAAQ,CAAC,MAAM,EAAE,CAAC;YACtB,CAAC,CAAC;QACN,CAAC;QAED,OAAO,SAAS,CAAC;IACrB,CAAC,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpC,MAAM,KAAK,GAAG,kBAAkB,CAC5B,WAAW,CAAC,GAAG,EAAE,CAAC,aAAa,EAAE,WAAW,CAAI,UAAU,CAAC,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,EACjJ,iBAAiB,CACpB,CAAC;IAEF,MAAM,QAAQ,GAAG,WAAW,CACxB,CAAC,QAA2B,EAAQ,EAAE;QAClC,MAAM,KAAK,GAAG,OAAO,QAAQ,KAAK,UAAU,CAAC,CAAC,CAAE,QAA2B,CAAC,aAAa,EAAE,WAAW,CAAI,UAAU,CAAC,IAAI,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC7J,aAAa,EAAE,YAAY,CAAI,UAAU,EAAE,KAAK,CAAC,CAAC;IACtD,CAAC,EACD,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,YAAY,CAAC,CAC3D,CAAC;IAEF,MAAM,UAAU,GAAG,WAAW,CAAC,GAAS,EAAE,CAAC,aAAa,EAAE,YAAY,CAAI,UAAU,EAAE,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC,aAAa,EAAE,UAAU,CAAC,GAAG,EAAE,UAAU,CAAC,YAAY,CAAC,CAAC,CAAC;IAE1K,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAU,CAAC;AAClD,CAAC","sourcesContent":["import { type Dispatch, type SetStateAction, useCallback, useEffect, useMemo } from \"react\";\r\n\r\nimport { type SettingDescriptor } from \"../services/settingsStore\";\r\n\r\nimport { Observable } from \"core/Misc/observable\";\r\nimport { useSettingsStore } from \"../contexts/settingsContext\";\r\nimport { useObservableState } from \"./observableHooks\";\r\n\r\n/**\r\n * Hook that reads and writes a setting from the settings store.\r\n * @param descriptor The setting descriptor that identifies the setting and its default value.\r\n * @returns A tuple of [currentValue, setValue, resetValue] similar to React's useState.\r\n */\r\nexport function useSetting<T>(descriptor: SettingDescriptor<T>): [T, Dispatch<SetStateAction<T>>, () => void] {\r\n    const settingsStore = useSettingsStore();\r\n\r\n    // Only watch for this specific setting to change. Otherwise, any time any setting changes we would\r\n    // call readSetting again, which if it is an object, it will be a new instance, which can cause\r\n    // unnecessary re-renders in consumers of this hook.\r\n    const settingObservable = useMemo(() => new Observable<void>(), []);\r\n    useEffect(() => {\r\n        if (settingsStore) {\r\n            const observer = settingsStore.onChanged.add((key) => {\r\n                if (key === descriptor.key) {\r\n                    settingObservable.notifyObservers();\r\n                }\r\n            });\r\n\r\n            return () => {\r\n                observer.remove();\r\n            };\r\n        }\r\n\r\n        return undefined;\r\n    }, [settingsStore, descriptor.key]);\r\n\r\n    const value = useObservableState(\r\n        useCallback(() => settingsStore?.readSetting<T>(descriptor) ?? descriptor.defaultValue, [settingsStore, descriptor.key, descriptor.defaultValue]),\r\n        settingObservable\r\n    );\r\n\r\n    const setValue = useCallback(\r\n        (newValue: SetStateAction<T>): void => {\r\n            const value = typeof newValue === \"function\" ? (newValue as (prev: T) => T)(settingsStore?.readSetting<T>(descriptor) ?? descriptor.defaultValue) : newValue;\r\n            settingsStore?.writeSetting<T>(descriptor, value);\r\n        },\r\n        [settingsStore, descriptor.key, descriptor.defaultValue]\r\n    );\r\n\r\n    const resetValue = useCallback((): void => settingsStore?.writeSetting<T>(descriptor, descriptor.defaultValue), [settingsStore, descriptor.key, descriptor.defaultValue]);\r\n\r\n    if (!settingsStore) {\r\n        throw new Error(\"Settings store is not available in context.\");\r\n    }\r\n\r\n    return [value, setValue, resetValue] as const;\r\n}\r\n"]}

package/modularTool/hooks/teachingMomentHooks.d.ts

@@ -0,0 +1,34 @@
+import { type Nullable } from "@babylonjs/core/index.js";
+import { type OnOpenChangeData, type PositioningImperativeRef } from "@fluentui/react-components";
+/**
+ * Creates a hook for managing teaching moment state.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state.
+ */
+export declare function MakeTeachingMoment(name: string): (suppress?: boolean) => {
+    readonly shouldDisplay: boolean;
+    readonly onDismissed: () => void;
+    readonly reset: () => void;
+};
+/**
+ * Creates a hook for managing teaching moment state for a dialog.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state for a dialog.
+ */
+export declare function MakeDialogTeachingMoment(name: string): (suppress?: boolean) => {
+    readonly shouldDisplay: boolean;
+    readonly onOpenChange: (e: unknown, data: OnOpenChangeData) => void;
+    readonly reset: () => void;
+};
+/**
+ * Creates a hook for managing teaching moment state for a popover.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state for a popover.
+ */
+export declare function MakePopoverTeachingMoment(name: string): (suppress?: boolean) => {
+    readonly shouldDisplay: boolean;
+    readonly positioningRef: import("react").Dispatch<import("react").SetStateAction<Nullable<PositioningImperativeRef>>>;
+    readonly targetRef: import("react").Dispatch<import("react").SetStateAction<Nullable<HTMLElement>>>;
+    readonly onOpenChange: (e: unknown, data: OnOpenChangeData) => void;
+    readonly reset: () => void;
+};

package/modularTool/hooks/teachingMomentHooks.js

@@ -0,0 +1,89 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useSetting } from "./settingsHooks.js";
+import { AsyncLock } from "@babylonjs/core/Misc/asyncLock.js";
+import { Deferred } from "@babylonjs/core/Misc/deferred.js";
+const SequencerLock = new AsyncLock();
+/**
+ * Creates a hook for managing teaching moment state.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state.
+ */
+export function MakeTeachingMoment(name) {
+    return (suppress) => {
+        const [hasDisplayed, setHasDisplayed, resetDisplayed] = useSetting({ key: `TeachingMoments/${name}`, defaultValue: false });
+        const [shouldDisplay, setShouldDisplay] = useState(false);
+        const deferredRef = useRef();
+        useEffect(() => {
+            if (!hasDisplayed && !suppress && !deferredRef.current) {
+                // eslint-disable-next-line @typescript-eslint/no-floating-promises
+                SequencerLock.lockAsync(async () => {
+                    deferredRef.current = new Deferred();
+                    setShouldDisplay(true);
+                    // Just hold the lock until the hook cleanup, which is effectively component unmount (e.g. the teaching moment is dismissed).
+                    await deferredRef.current.promise;
+                });
+            }
+            return () => {
+                deferredRef.current?.resolve();
+            };
+        }, [hasDisplayed, suppress]);
+        const onDismissed = useCallback(() => {
+            setHasDisplayed(true);
+            deferredRef.current?.resolve();
+            deferredRef.current = undefined;
+            setShouldDisplay(false);
+        }, []);
+        return {
+            shouldDisplay,
+            onDismissed,
+            reset: resetDisplayed,
+        };
+    };
+}
+/**
+ * Creates a hook for managing teaching moment state for a dialog.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state for a dialog.
+ */
+export function MakeDialogTeachingMoment(name) {
+    const useTeachingMoment = MakeTeachingMoment(name);
+    return (suppress) => {
+        const { shouldDisplay, onDismissed, reset } = useTeachingMoment(suppress);
+        const onOpenChange = useCallback((e, data) => {
+            if (!data.open) {
+                onDismissed();
+            }
+        }, []);
+        return {
+            shouldDisplay,
+            onOpenChange,
+            reset,
+        };
+    };
+}
+/**
+ * Creates a hook for managing teaching moment state for a popover.
+ * @param name The unique name of the teaching moment.
+ * @returns A hook that returns the teaching moment state for a popover.
+ */
+export function MakePopoverTeachingMoment(name) {
+    const useDialogTeachingMoment = MakeDialogTeachingMoment(name);
+    return (suppress) => {
+        const [target, setTarget] = useState(null);
+        const [positioningRef, setPositioningRef] = useState(null);
+        const { shouldDisplay, onOpenChange, reset } = useDialogTeachingMoment(suppress || !target || !positioningRef);
+        useEffect(() => {
+            if (target && positioningRef) {
+                positioningRef.setTarget(target);
+            }
+        }, [target, positioningRef]);
+        return {
+            shouldDisplay,
+            positioningRef: setPositioningRef,
+            targetRef: setTarget,
+            onOpenChange,
+            reset,
+        };
+    };
+}
+//# sourceMappingURL=teachingMomentHooks.js.map

package/modularTool/hooks/teachingMomentHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"teachingMomentHooks.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/hooks/teachingMomentHooks.ts"],"names":[],"mappings":"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","sourcesContent":["import { type Nullable } from \"core/index\";\r\n\r\nimport { type OnOpenChangeData, type PositioningImperativeRef } from \"@fluentui/react-components\";\r\n\r\nimport { useCallback, useEffect, useRef, useState } from \"react\";\r\nimport { useSetting } from \"./settingsHooks\";\r\n\r\nimport { AsyncLock } from \"core/Misc/asyncLock\";\r\nimport { Deferred } from \"core/Misc/deferred\";\r\n\r\nconst SequencerLock = new AsyncLock();\r\n\r\n/**\r\n * Creates a hook for managing teaching moment state.\r\n * @param name The unique name of the teaching moment.\r\n * @returns A hook that returns the teaching moment state.\r\n */\r\nexport function MakeTeachingMoment(name: string) {\r\n    return (suppress?: boolean) => {\r\n        const [hasDisplayed, setHasDisplayed, resetDisplayed] = useSetting({ key: `TeachingMoments/${name}`, defaultValue: false });\r\n        const [shouldDisplay, setShouldDisplay] = useState(false);\r\n\r\n        const deferredRef = useRef<Deferred<void>>();\r\n\r\n        useEffect(() => {\r\n            if (!hasDisplayed && !suppress && !deferredRef.current) {\r\n                // eslint-disable-next-line @typescript-eslint/no-floating-promises\r\n                SequencerLock.lockAsync(async () => {\r\n                    deferredRef.current = new Deferred<void>();\r\n                    setShouldDisplay(true);\r\n                    // Just hold the lock until the hook cleanup, which is effectively component unmount (e.g. the teaching moment is dismissed).\r\n                    await deferredRef.current.promise;\r\n                });\r\n            }\r\n\r\n            return () => {\r\n                deferredRef.current?.resolve();\r\n            };\r\n        }, [hasDisplayed, suppress]);\r\n\r\n        const onDismissed = useCallback(() => {\r\n            setHasDisplayed(true);\r\n            deferredRef.current?.resolve();\r\n            deferredRef.current = undefined;\r\n            setShouldDisplay(false);\r\n        }, []);\r\n\r\n        return {\r\n            shouldDisplay,\r\n            onDismissed,\r\n            reset: resetDisplayed,\r\n        } as const;\r\n    };\r\n}\r\n\r\n/**\r\n * Creates a hook for managing teaching moment state for a dialog.\r\n * @param name The unique name of the teaching moment.\r\n * @returns A hook that returns the teaching moment state for a dialog.\r\n */\r\nexport function MakeDialogTeachingMoment(name: string) {\r\n    const useTeachingMoment = MakeTeachingMoment(name);\r\n\r\n    return (suppress?: boolean) => {\r\n        const { shouldDisplay, onDismissed, reset } = useTeachingMoment(suppress);\r\n\r\n        const onOpenChange = useCallback((e: unknown, data: OnOpenChangeData) => {\r\n            if (!data.open) {\r\n                onDismissed();\r\n            }\r\n        }, []);\r\n\r\n        return {\r\n            shouldDisplay,\r\n            onOpenChange,\r\n            reset,\r\n        } as const;\r\n    };\r\n}\r\n\r\n/**\r\n * Creates a hook for managing teaching moment state for a popover.\r\n * @param name The unique name of the teaching moment.\r\n * @returns A hook that returns the teaching moment state for a popover.\r\n */\r\nexport function MakePopoverTeachingMoment(name: string) {\r\n    const useDialogTeachingMoment = MakeDialogTeachingMoment(name);\r\n\r\n    return (suppress?: boolean) => {\r\n        const [target, setTarget] = useState<Nullable<HTMLElement>>(null);\r\n        const [positioningRef, setPositioningRef] = useState<Nullable<PositioningImperativeRef>>(null);\r\n\r\n        const { shouldDisplay, onOpenChange, reset } = useDialogTeachingMoment(suppress || !target || !positioningRef);\r\n\r\n        useEffect(() => {\r\n            if (target && positioningRef) {\r\n                positioningRef.setTarget(target);\r\n            }\r\n        }, [target, positioningRef]);\r\n\r\n        return {\r\n            shouldDisplay,\r\n            positioningRef: setPositioningRef,\r\n            targetRef: setTarget,\r\n            onOpenChange,\r\n            reset,\r\n        } as const;\r\n    };\r\n}\r\n"]}

package/modularTool/hooks/themeHooks.d.ts

@@ -0,0 +1,17 @@
+import { type ThemeMode } from "../services/themeService.js";
+/**
+ * Hook that provides the current theme mode state and controls for changing it.
+ * @returns An object with the current dark mode state, theme mode, and functions to set or toggle the theme.
+ */
+export declare function useThemeMode(): {
+    readonly isDarkMode: boolean;
+    readonly themeMode: ThemeMode;
+    readonly setThemeMode: (mode: ThemeMode) => void;
+    readonly toggleThemeMode: () => void | undefined;
+};
+/**
+ * Hook that returns the current Fluent UI theme based on the active theme mode.
+ * @param invert If true, inverts the theme (returns light theme in dark mode and vice versa). Defaults to false.
+ * @returns The current Fluent UI theme object.
+ */
+export declare function useTheme(invert?: boolean): import("@fluentui/tokens").Theme;

package/modularTool/hooks/themeHooks.js

@@ -0,0 +1,38 @@
+import { ThemeModeSettingDescriptor, ThemeResolver } from "../services/themeService.js";
+import { useCallback } from "react";
+import { useSettingsStore } from "../contexts/settingsContext.js";
+import { DarkTheme, LightTheme } from "../themes/babylonTheme.js";
+import { useObservableState } from "./observableHooks.js";
+import { useResource } from "./resourceHooks.js";
+/**
+ * Hook that provides the current theme mode state and controls for changing it.
+ * @returns An object with the current dark mode state, theme mode, and functions to set or toggle the theme.
+ */
+export function useThemeMode() {
+    const settingsStore = useSettingsStore();
+    const themeResolver = useResource(useCallback(() => (settingsStore ? new ThemeResolver(settingsStore) : undefined), [settingsStore]));
+    const state = useObservableState(useCallback(() => ({
+        isDarkMode: themeResolver?.isDark ?? false,
+        themeMode: themeResolver?.mode ?? ThemeModeSettingDescriptor.defaultValue,
+        setThemeMode: (mode) => {
+            if (themeResolver) {
+                themeResolver.mode = mode;
+            }
+        },
+        toggleThemeMode: () => themeResolver?.toggle(),
+    }), [themeResolver]), themeResolver?.onChanged);
+    if (!themeResolver) {
+        throw new Error("Settings store is not available in context.");
+    }
+    return state;
+}
+/**
+ * Hook that returns the current Fluent UI theme based on the active theme mode.
+ * @param invert If true, inverts the theme (returns light theme in dark mode and vice versa). Defaults to false.
+ * @returns The current Fluent UI theme object.
+ */
+export function useTheme(invert = false) {
+    const { isDarkMode } = useThemeMode();
+    return isDarkMode !== invert ? DarkTheme : LightTheme;
+}
+//# sourceMappingURL=themeHooks.js.map

package/modularTool/hooks/themeHooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"themeHooks.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/hooks/themeHooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,0BAA0B,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAErG,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAEpC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9C;;;GAGG;AACH,MAAM,UAAU,YAAY;IACxB,MAAM,aAAa,GAAG,gBAAgB,EAAE,CAAC;IACzC,MAAM,aAAa,GAAG,WAAW,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAEtI,MAAM,KAAK,GAAG,kBAAkB,CAC5B,WAAW,CACP,GAAG,EAAE,CACD,CAAC;QACG,UAAU,EAAE,aAAa,EAAE,MAAM,IAAI,KAAK;QAC1C,SAAS,EAAE,aAAa,EAAE,IAAI,IAAI,0BAA0B,CAAC,YAAY;QACzE,YAAY,EAAE,CAAC,IAAe,EAAE,EAAE;YAC9B,IAAI,aAAa,EAAE,CAAC;gBAChB,aAAa,CAAC,IAAI,GAAG,IAAI,CAAC;YAC9B,CAAC;QACL,CAAC;QACD,eAAe,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,MAAM,EAAE;KACjD,CAAU,EACf,CAAC,aAAa,CAAC,CAClB,EACD,aAAa,EAAE,SAAS,CAC3B,CAAC;IAEF,IAAI,CAAC,aAAa,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,6CAA6C,CAAC,CAAC;IACnE,CAAC;IAED,OAAO,KAAK,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAM,GAAG,KAAK;IACnC,MAAM,EAAE,UAAU,EAAE,GAAG,YAAY,EAAE,CAAC;IACtC,OAAO,UAAU,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC;AAC1D,CAAC","sourcesContent":["import { type ThemeMode, ThemeModeSettingDescriptor, ThemeResolver } from \"../services/themeService\";\r\n\r\nimport { useCallback } from \"react\";\r\n\r\nimport { useSettingsStore } from \"../contexts/settingsContext\";\r\nimport { DarkTheme, LightTheme } from \"../themes/babylonTheme\";\r\nimport { useObservableState } from \"./observableHooks\";\r\nimport { useResource } from \"./resourceHooks\";\r\n\r\n/**\r\n * Hook that provides the current theme mode state and controls for changing it.\r\n * @returns An object with the current dark mode state, theme mode, and functions to set or toggle the theme.\r\n */\r\nexport function useThemeMode() {\r\n    const settingsStore = useSettingsStore();\r\n    const themeResolver = useResource(useCallback(() => (settingsStore ? new ThemeResolver(settingsStore) : undefined), [settingsStore]));\r\n\r\n    const state = useObservableState(\r\n        useCallback(\r\n            () =>\r\n                ({\r\n                    isDarkMode: themeResolver?.isDark ?? false,\r\n                    themeMode: themeResolver?.mode ?? ThemeModeSettingDescriptor.defaultValue,\r\n                    setThemeMode: (mode: ThemeMode) => {\r\n                        if (themeResolver) {\r\n                            themeResolver.mode = mode;\r\n                        }\r\n                    },\r\n                    toggleThemeMode: () => themeResolver?.toggle(),\r\n                }) as const,\r\n            [themeResolver]\r\n        ),\r\n        themeResolver?.onChanged\r\n    );\r\n\r\n    if (!themeResolver) {\r\n        throw new Error(\"Settings store is not available in context.\");\r\n    }\r\n\r\n    return state;\r\n}\r\n\r\n/**\r\n * Hook that returns the current Fluent UI theme based on the active theme mode.\r\n * @param invert If true, inverts the theme (returns light theme in dark mode and vice versa). Defaults to false.\r\n * @returns The current Fluent UI theme object.\r\n */\r\nexport function useTheme(invert = false) {\r\n    const { isDarkMode } = useThemeMode();\r\n    return isDarkMode !== invert ? DarkTheme : LightTheme;\r\n}\r\n"]}

package/modularTool/hooks/useResizeHandle.d.ts

@@ -0,0 +1,35 @@
+export type GrowDirection = "end" | "start" | "up" | "down";
+export type UseResizeHandleParams = {
+    /**
+     * The direction in which the element is considered growing in size ('end', 'start', 'up', or 'down').
+     */
+    growDirection: GrowDirection;
+    /**
+     * The name of the CSS variable that will be set on the wrapper element to reflect the current size of the element.
+     */
+    variableName: string;
+    /**
+     * A callback that will be called when the element is resized.
+     *
+     * @remarks The passed function should be memoized for better performance.
+     */
+    onChange?: (value: number) => void;
+    /**
+     * The minimum change allowed (e.g. the smallest negative number allowed).
+     */
+    minValue?: number;
+    /**
+     * The maximum change allowed (e.g. the largest positive number allowed).
+     */
+    maxValue?: number;
+};
+/**
+ * A custom hook that helps with element resizing.
+ * @param params The parameters for the resize handle.
+ * @returns An object containing refs and a function to set the value.
+ */
+export declare function useResizeHandle(params: UseResizeHandleParams): {
+    elementRef: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    handleRef: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    setValue: (value: number) => void;
+};

package/modularTool/hooks/useResizeHandle.js

@@ -0,0 +1,75 @@
+// NOTE: This is basically a super simplified version of https://github.com/microsoft/fluentui-contrib/blob/main/packages/react-resize-handle/src/hooks
+// This version does not support keyboard interactions, absolute values, automatically clamping to the actual adjusted size, accessibility, and various other features.
+// We can switch back to Fluent's implementation once some known bugs are fixed:
+// 1. https://github.com/microsoft/fluentui-contrib/issues/523
+// 2. React 19 compatibility
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Clamp } from "@babylonjs/core/Maths/math.scalar.functions.js";
+/**
+ * A custom hook that helps with element resizing.
+ * @param params The parameters for the resize handle.
+ * @returns An object containing refs and a function to set the value.
+ */
+export function useResizeHandle(params) {
+    const { growDirection, variableName, onChange } = params;
+    const valueRef = useRef(0);
+    const [elementRef, setElementRef] = useState(null);
+    const [handleRef, setHandleRef] = useState(null);
+    const updateElementStyle = useCallback((value) => {
+        if (elementRef) {
+            elementRef.style.setProperty(variableName, `${value}px`);
+        }
+    }, [elementRef, variableName]);
+    const setValue = useCallback((value) => {
+        valueRef.current = value;
+        updateElementStyle(value);
+        onChange?.(value);
+    }, [updateElementStyle, onChange]);
+    useEffect(() => {
+        updateElementStyle(valueRef.current);
+    }, [updateElementStyle]);
+    useEffect(() => {
+        if (handleRef) {
+            let delta = 0;
+            const coerceDelta = (delta) => Clamp(delta, params.minValue ?? -Infinity, params.maxValue ?? Infinity);
+            const onPointerMove = (event) => {
+                event.preventDefault();
+                switch (growDirection) {
+                    case "up":
+                        delta -= event.movementY;
+                        break;
+                    case "down":
+                        delta += event.movementY;
+                        break;
+                    case "start":
+                        delta -= event.movementX;
+                        break;
+                    case "end":
+                        delta += event.movementX;
+                        break;
+                }
+                setValue(coerceDelta(delta));
+            };
+            const onPointerDown = (event) => {
+                event.preventDefault();
+                delta = valueRef.current;
+                handleRef.setPointerCapture(event.pointerId);
+                handleRef.addEventListener("pointermove", onPointerMove);
+            };
+            const onPointerUp = (event) => {
+                event.preventDefault();
+                handleRef.releasePointerCapture(event.pointerId);
+                handleRef.removeEventListener("pointermove", onPointerMove);
+                valueRef.current = coerceDelta(valueRef.current);
+            };
+            handleRef.addEventListener("pointerdown", onPointerDown);
+            handleRef.addEventListener("pointerup", onPointerUp);
+        }
+    }, [handleRef, setValue]);
+    return {
+        elementRef: setElementRef,
+        handleRef: setHandleRef,
+        setValue,
+    };
+}
+//# sourceMappingURL=useResizeHandle.js.map

package/modularTool/hooks/useResizeHandle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useResizeHandle.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/hooks/useResizeHandle.ts"],"names":[],"mappings":"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","sourcesContent":["// NOTE: This is basically a super simplified version of https://github.com/microsoft/fluentui-contrib/blob/main/packages/react-resize-handle/src/hooks\r\n// This version does not support keyboard interactions, absolute values, automatically clamping to the actual adjusted size, accessibility, and various other features.\r\n// We can switch back to Fluent's implementation once some known bugs are fixed:\r\n// 1. https://github.com/microsoft/fluentui-contrib/issues/523\r\n// 2. React 19 compatibility\r\n\r\nimport { useCallback, useEffect, useRef, useState } from \"react\";\r\n\r\nimport { Clamp } from \"core/Maths/math.scalar.functions\";\r\n\r\nexport type GrowDirection = \"end\" | \"start\" | \"up\" | \"down\";\r\n\r\nexport type UseResizeHandleParams = {\r\n    /**\r\n     * The direction in which the element is considered growing in size ('end', 'start', 'up', or 'down').\r\n     */\r\n    growDirection: GrowDirection;\r\n    /**\r\n     * The name of the CSS variable that will be set on the wrapper element to reflect the current size of the element.\r\n     */\r\n    variableName: string;\r\n    /**\r\n     * A callback that will be called when the element is resized.\r\n     *\r\n     * @remarks The passed function should be memoized for better performance.\r\n     */\r\n    onChange?: (value: number) => void;\r\n    /**\r\n     * The minimum change allowed (e.g. the smallest negative number allowed).\r\n     */\r\n    minValue?: number;\r\n    /**\r\n     * The maximum change allowed (e.g. the largest positive number allowed).\r\n     */\r\n    maxValue?: number;\r\n};\r\n\r\n/**\r\n * A custom hook that helps with element resizing.\r\n * @param params The parameters for the resize handle.\r\n * @returns An object containing refs and a function to set the value.\r\n */\r\nexport function useResizeHandle(params: UseResizeHandleParams) {\r\n    const { growDirection, variableName, onChange } = params;\r\n\r\n    const valueRef = useRef(0);\r\n    const [elementRef, setElementRef] = useState<HTMLElement | null>(null);\r\n    const [handleRef, setHandleRef] = useState<HTMLElement | null>(null);\r\n\r\n    const updateElementStyle = useCallback(\r\n        (value: number) => {\r\n            if (elementRef) {\r\n                elementRef.style.setProperty(variableName, `${value}px`);\r\n            }\r\n        },\r\n        [elementRef, variableName]\r\n    );\r\n\r\n    const setValue = useCallback(\r\n        (value: number) => {\r\n            valueRef.current = value;\r\n            updateElementStyle(value);\r\n            onChange?.(value);\r\n        },\r\n        [updateElementStyle, onChange]\r\n    );\r\n\r\n    useEffect(() => {\r\n        updateElementStyle(valueRef.current);\r\n    }, [updateElementStyle]);\r\n\r\n    useEffect(() => {\r\n        if (handleRef) {\r\n            let delta = 0;\r\n\r\n            const coerceDelta = (delta: number) => Clamp(delta, params.minValue ?? -Infinity, params.maxValue ?? Infinity);\r\n\r\n            const onPointerMove = (event: PointerEvent) => {\r\n                event.preventDefault();\r\n                switch (growDirection) {\r\n                    case \"up\":\r\n                        delta -= event.movementY;\r\n                        break;\r\n                    case \"down\":\r\n                        delta += event.movementY;\r\n                        break;\r\n                    case \"start\":\r\n                        delta -= event.movementX;\r\n                        break;\r\n                    case \"end\":\r\n                        delta += event.movementX;\r\n                        break;\r\n                }\r\n                setValue(coerceDelta(delta));\r\n            };\r\n\r\n            const onPointerDown = (event: PointerEvent) => {\r\n                event.preventDefault();\r\n                delta = valueRef.current;\r\n                handleRef.setPointerCapture(event.pointerId);\r\n                handleRef.addEventListener(\"pointermove\", onPointerMove);\r\n            };\r\n\r\n            const onPointerUp = (event: PointerEvent) => {\r\n                event.preventDefault();\r\n                handleRef.releasePointerCapture(event.pointerId);\r\n                handleRef.removeEventListener(\"pointermove\", onPointerMove);\r\n                valueRef.current = coerceDelta(valueRef.current);\r\n            };\r\n\r\n            handleRef.addEventListener(\"pointerdown\", onPointerDown);\r\n            handleRef.addEventListener(\"pointerup\", onPointerUp);\r\n        }\r\n    }, [handleRef, setValue]);\r\n\r\n    return {\r\n        elementRef: setElementRef,\r\n        handleRef: setHandleRef,\r\n        setValue,\r\n    };\r\n}\r\n"]}

package/modularTool/misc/assert.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Asserts that the given value is truthy.
+ * @param value The value to check.
+ */
+export declare function Assert(value: unknown): asserts value;

package/modularTool/misc/assert.js

@@ -0,0 +1,10 @@
+/**
+ * Asserts that the given value is truthy.
+ * @param value The value to check.
+ */
+export function Assert(value) {
+    if (!value) {
+        throw new Error("assertion failed");
+    }
+}
+//# sourceMappingURL=assert.js.map

package/modularTool/misc/assert.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/misc/assert.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IACxC,CAAC;AACL,CAAC","sourcesContent":["/**\r\n * Asserts that the given value is truthy.\r\n * @param value The value to check.\r\n */\r\nexport function Assert(value: unknown): asserts value {\r\n    if (!value) {\r\n        throw new Error(\"assertion failed\");\r\n    }\r\n}\r\n"]}

package/modularTool/misc/graphUtils.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Performs a topological sort on a graph.
+ * @param graph The set of nodes that make up the graph.
+ * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+ * @param onSortedNode A function that is called for each node in the sorted order.
+ * @remarks
+ * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.
+ */
+export declare function SortGraph<NodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT>, onSortedNode: (node: NodeT) => void): void;
+/**
+ * Traverses a graph.
+ * @param graph The set of nodes that make up the graph.
+ * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+ * @param onBeforeTraverse A function that is called before traversing each node.
+ * @param onAfterTraverse A function that is called after traversing each node.
+ * @remarks
+ * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.
+ */
+export declare function TraverseGraph<NodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT> | null | undefined, onBeforeTraverse?: (node: NodeT) => void, onAfterTraverse?: (node: NodeT) => void): void;
+/**
+ * A utility class for performing graph operations.
+ * @remarks
+ * The class allocates new objects, but each operation (e.g. sort, traverse) is allocation free. This is useful when used in the hot path.
+ */
+export declare class GraphUtils<DefaultNodeT = unknown> {
+    private readonly _traversalState;
+    private _isTraversing;
+    /**
+     * Performs a topological sort on a graph.
+     * @param graph The set of nodes that make up the graph.
+     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+     * @param onSortedNode A function that is called for each node in the sorted order.
+     */
+    sort<NodeT extends DefaultNodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT>, onSortedNode: (node: NodeT) => void): void;
+    /**
+     * Traverses a graph.
+     * @param graph The set of nodes that make up the graph.
+     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+     * @param onBeforeTraverse A function that is called before traversing each node.
+     * @param onAfterTraverse A function that is called after traversing each node.
+     */
+    traverse<NodeT extends DefaultNodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT> | null | undefined, onBeforeTraverse?: (node: NodeT) => void, onAfterTraverse?: (node: NodeT) => void): void;
+    private _traverseCore;
+}

package/modularTool/misc/graphUtils.js

@@ -0,0 +1,90 @@
+/**
+ * Performs a topological sort on a graph.
+ * @param graph The set of nodes that make up the graph.
+ * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+ * @param onSortedNode A function that is called for each node in the sorted order.
+ * @remarks
+ * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.
+ */
+export function SortGraph(graph, getAdjacentNodes, onSortedNode) {
+    const sorter = new GraphUtils();
+    sorter.sort(graph, getAdjacentNodes, onSortedNode);
+}
+/**
+ * Traverses a graph.
+ * @param graph The set of nodes that make up the graph.
+ * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+ * @param onBeforeTraverse A function that is called before traversing each node.
+ * @param onAfterTraverse A function that is called after traversing each node.
+ * @remarks
+ * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.
+ */
+export function TraverseGraph(graph, getAdjacentNodes, onBeforeTraverse, onAfterTraverse) {
+    const traverser = new GraphUtils();
+    traverser.traverse(graph, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);
+}
+/**
+ * A utility class for performing graph operations.
+ * @remarks
+ * The class allocates new objects, but each operation (e.g. sort, traverse) is allocation free. This is useful when used in the hot path.
+ */
+export class GraphUtils {
+    constructor() {
+        // Tracks three states:
+        // 1. No entry for the node - this means the node has not been encountered yet during any traversal
+        // 2. Entry with value false - this means the node is currently being traversed (needed to detect cycles)
+        // 3. Entry with value true - this means the node has already been fully traversed (and cycles were not detected)
+        this._traversalState = new Map();
+        this._isTraversing = false;
+    }
+    /**
+     * Performs a topological sort on a graph.
+     * @param graph The set of nodes that make up the graph.
+     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+     * @param onSortedNode A function that is called for each node in the sorted order.
+     */
+    sort(graph, getAdjacentNodes, onSortedNode) {
+        this.traverse(graph, getAdjacentNodes, undefined, onSortedNode);
+    }
+    /**
+     * Traverses a graph.
+     * @param graph The set of nodes that make up the graph.
+     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.
+     * @param onBeforeTraverse A function that is called before traversing each node.
+     * @param onAfterTraverse A function that is called after traversing each node.
+     */
+    traverse(graph, getAdjacentNodes, onBeforeTraverse, onAfterTraverse) {
+        // Since the traversal state is re-used, disallow re-entrancy through the getAdjacentNodes or onBeforeTraverse or onAfterTraverse callbacks.
+        if (this._isTraversing) {
+            throw new Error("This TopologicalSorter instance is already traversing.");
+        }
+        this._isTraversing = true;
+        try {
+            for (const node of graph) {
+                this._traverseCore(node, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);
+            }
+        }
+        finally {
+            this._isTraversing = false;
+            this._traversalState.clear();
+        }
+    }
+    _traverseCore(node, getAdjacentNodes, onBeforeTraverse, onAfterTraverse) {
+        if (this._traversalState.get(node) !== true) {
+            if (this._traversalState.get(node) === false) {
+                throw new Error("Graph has cycle.");
+            }
+            this._traversalState.set(node, false);
+            onBeforeTraverse?.(node);
+            const adjacentNodes = getAdjacentNodes(node);
+            if (adjacentNodes) {
+                for (const adjacentNode of adjacentNodes) {
+                    this._traverseCore(adjacentNode, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);
+                }
+            }
+            this._traversalState.set(node, true);
+            onAfterTraverse?.(node);
+        }
+    }
+}
+//# sourceMappingURL=graphUtils.js.map

package/modularTool/misc/graphUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graphUtils.js","sourceRoot":"","sources":["../../../../../dev/sharedUiComponents/src/modularTool/misc/graphUtils.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAQ,KAAsB,EAAE,gBAAkD,EAAE,YAAmC;IAC5I,MAAM,MAAM,GAAG,IAAI,UAAU,EAAS,CAAC;IACvC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CACzB,KAAsB,EACtB,gBAAqE,EACrE,gBAAwC,EACxC,eAAuC;IAEvC,MAAM,SAAS,GAAG,IAAI,UAAU,EAAS,CAAC;IAC1C,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC;AACnF,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAU;IAAvB;QACI,uBAAuB;QACvB,mGAAmG;QACnG,yGAAyG;QACzG,iHAAiH;QAChG,oBAAe,GAAG,IAAI,GAAG,EAAyB,CAAC;QAC5D,kBAAa,GAAG,KAAK,CAAC;IAmElC,CAAC;IAjEG;;;;;OAKG;IACI,IAAI,CAA6B,KAAsB,EAAE,gBAAkD,EAAE,YAAmC;QACnJ,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;IACpE,CAAC;IAED;;;;;;OAMG;IACI,QAAQ,CACX,KAAsB,EACtB,gBAAqE,EACrE,gBAAwC,EACxC,eAAuC;QAEvC,4IAA4I;QAC5I,IAAI,IAAI,CAAC,aAAa,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,wDAAwD,CAAC,CAAC;QAC9E,CAAC;QAED,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;QAE1B,IAAI,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACvB,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC;YAClF,CAAC;QACL,CAAC;gBAAS,CAAC;YACP,IAAI,CAAC,aAAa,GAAG,KAAK,CAAC;YAC3B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;QACjC,CAAC;IACL,CAAC;IAEO,aAAa,CACjB,IAAW,EACX,gBAAqE,EACrE,gBAAwC,EACxC,eAAuC;QAEvC,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,IAAI,EAAE,CAAC;YAC1C,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,KAAK,EAAE,CAAC;gBAC3C,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;YACxC,CAAC;YAED,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YACtC,gBAAgB,EAAE,CAAC,IAAI,CAAC,CAAC;YAEzB,MAAM,aAAa,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YAC7C,IAAI,aAAa,EAAE,CAAC;gBAChB,KAAK,MAAM,YAAY,IAAI,aAAa,EAAE,CAAC;oBACvC,IAAI,CAAC,aAAa,CAAC,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC;gBAC1F,CAAC;YACL,CAAC;YAED,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACrC,eAAe,EAAE,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;IACL,CAAC;CACJ","sourcesContent":["/**\r\n * Performs a topological sort on a graph.\r\n * @param graph The set of nodes that make up the graph.\r\n * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.\r\n * @param onSortedNode A function that is called for each node in the sorted order.\r\n * @remarks\r\n * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.\r\n */\r\nexport function SortGraph<NodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT>, onSortedNode: (node: NodeT) => void) {\r\n    const sorter = new GraphUtils<NodeT>();\r\n    sorter.sort(graph, getAdjacentNodes, onSortedNode);\r\n}\r\n\r\n/**\r\n * Traverses a graph.\r\n * @param graph The set of nodes that make up the graph.\r\n * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.\r\n * @param onBeforeTraverse A function that is called before traversing each node.\r\n * @param onAfterTraverse A function that is called after traversing each node.\r\n * @remarks\r\n * This function allocates. Do not use it in the hot path. Instead use an instance of GraphUtils.\r\n */\r\nexport function TraverseGraph<NodeT>(\r\n    graph: Iterable<NodeT>,\r\n    getAdjacentNodes: (node: NodeT) => Iterable<NodeT> | null | undefined,\r\n    onBeforeTraverse?: (node: NodeT) => void,\r\n    onAfterTraverse?: (node: NodeT) => void\r\n) {\r\n    const traverser = new GraphUtils<NodeT>();\r\n    traverser.traverse(graph, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);\r\n}\r\n\r\n/**\r\n * A utility class for performing graph operations.\r\n * @remarks\r\n * The class allocates new objects, but each operation (e.g. sort, traverse) is allocation free. This is useful when used in the hot path.\r\n */\r\nexport class GraphUtils<DefaultNodeT = unknown> {\r\n    // Tracks three states:\r\n    // 1. No entry for the node - this means the node has not been encountered yet during any traversal\r\n    // 2. Entry with value false - this means the node is currently being traversed (needed to detect cycles)\r\n    // 3. Entry with value true - this means the node has already been fully traversed (and cycles were not detected)\r\n    private readonly _traversalState = new Map<DefaultNodeT, boolean>();\r\n    private _isTraversing = false;\r\n\r\n    /**\r\n     * Performs a topological sort on a graph.\r\n     * @param graph The set of nodes that make up the graph.\r\n     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.\r\n     * @param onSortedNode A function that is called for each node in the sorted order.\r\n     */\r\n    public sort<NodeT extends DefaultNodeT>(graph: Iterable<NodeT>, getAdjacentNodes: (node: NodeT) => Iterable<NodeT>, onSortedNode: (node: NodeT) => void) {\r\n        this.traverse(graph, getAdjacentNodes, undefined, onSortedNode);\r\n    }\r\n\r\n    /**\r\n     * Traverses a graph.\r\n     * @param graph The set of nodes that make up the graph.\r\n     * @param getAdjacentNodes A function that returns the adjacent nodes for a given node.\r\n     * @param onBeforeTraverse A function that is called before traversing each node.\r\n     * @param onAfterTraverse A function that is called after traversing each node.\r\n     */\r\n    public traverse<NodeT extends DefaultNodeT>(\r\n        graph: Iterable<NodeT>,\r\n        getAdjacentNodes: (node: NodeT) => Iterable<NodeT> | null | undefined,\r\n        onBeforeTraverse?: (node: NodeT) => void,\r\n        onAfterTraverse?: (node: NodeT) => void\r\n    ) {\r\n        // Since the traversal state is re-used, disallow re-entrancy through the getAdjacentNodes or onBeforeTraverse or onAfterTraverse callbacks.\r\n        if (this._isTraversing) {\r\n            throw new Error(\"This TopologicalSorter instance is already traversing.\");\r\n        }\r\n\r\n        this._isTraversing = true;\r\n\r\n        try {\r\n            for (const node of graph) {\r\n                this._traverseCore(node, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);\r\n            }\r\n        } finally {\r\n            this._isTraversing = false;\r\n            this._traversalState.clear();\r\n        }\r\n    }\r\n\r\n    private _traverseCore<NodeT extends DefaultNodeT>(\r\n        node: NodeT,\r\n        getAdjacentNodes: (node: NodeT) => Iterable<NodeT> | null | undefined,\r\n        onBeforeTraverse?: (node: NodeT) => void,\r\n        onAfterTraverse?: (node: NodeT) => void\r\n    ) {\r\n        if (this._traversalState.get(node) !== true) {\r\n            if (this._traversalState.get(node) === false) {\r\n                throw new Error(\"Graph has cycle.\");\r\n            }\r\n\r\n            this._traversalState.set(node, false);\r\n            onBeforeTraverse?.(node);\r\n\r\n            const adjacentNodes = getAdjacentNodes(node);\r\n            if (adjacentNodes) {\r\n                for (const adjacentNode of adjacentNodes) {\r\n                    this._traverseCore(adjacentNode, getAdjacentNodes, onBeforeTraverse, onAfterTraverse);\r\n                }\r\n            }\r\n\r\n            this._traversalState.set(node, true);\r\n            onAfterTraverse?.(node);\r\n        }\r\n    }\r\n}\r\n"]}

package/modularTool/misc/observableCollection.d.ts

@@ -0,0 +1,23 @@
+import { type IDisposable, type IReadonlyObservable } from "@babylonjs/core/index.js";
+/**
+ * A collection of items that can be observed for changes.
+ */
+export declare class ObservableCollection<T> {
+    private readonly _items;
+    private readonly _keys;
+    private readonly _observable;
+    /**
+     * An observable that notifies observers when the collection changes.
+     */
+    get observable(): IReadonlyObservable<void>;
+    /**
+     * The items in the collection.
+     */
+    get items(): readonly T[];
+    /**
+     * Adds an item to the collection.
+     * @param item The item to add.
+     * @returns A disposable that removes the item from the collection when disposed.
+     */
+    add(item: T): IDisposable;
+}

package/modularTool/misc/observableCollection.js

@@ -0,0 +1,43 @@
+import { Observable } from "@babylonjs/core/Misc/observable.js";
+/**
+ * A collection of items that can be observed for changes.
+ */
+export class ObservableCollection {
+    constructor() {
+        this._items = [];
+        this._keys = [];
+        this._observable = new Observable();
+    }
+    /**
+     * An observable that notifies observers when the collection changes.
+     */
+    get observable() {
+        return this._observable;
+    }
+    /**
+     * The items in the collection.
+     */
+    get items() {
+        return this._items;
+    }
+    /**
+     * Adds an item to the collection.
+     * @param item The item to add.
+     * @returns A disposable that removes the item from the collection when disposed.
+     */
+    add(item) {
+        const key = Symbol();
+        this._items.push(item);
+        this._keys.push(key);
+        this._observable.notifyObservers();
+        return {
+            dispose: () => {
+                const index = this._keys.indexOf(key);
+                this._items.splice(index, 1);
+                this._keys.splice(index, 1);
+                this._observable.notifyObservers();
+            },
+        };
+    }
+}
+//# sourceMappingURL=observableCollection.js.map