@bariskuran/base 0.0.0-stage → 0.0.1

package/src/libs/useImagePreloader/_dS.jsx

@@ -0,0 +1,50 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { useImagePreloader } from ".";
+import { Typo } from "../Typo";
+
+const X = () => {
+    const isLoaded = useImagePreloader(
+        ["https://picsum.photos/80/80?random=1", "https://picsum.photos/80/80?random=2"],
+        { delayAfterLoad: 200 },
+    );
+
+    return (
+        <Ds.page
+            title="useImagePreloader()"
+            releasedOn="1.0.0"
+            description="Preloads image URLs and returns readiness state."
+        >
+            <Ds.block
+                title="Preload Image List"
+                code={`import { useImagePreloader } from "${SYS.basePath}";
+
+                       const isLoaded = useImagePreloader(["/a.png", "/b.png"], { delayAfterLoad: 150 });`}
+                example={<Typo.span>{`images loaded: ${String(isLoaded)}`}</Typo.span>}
+            />
+            <Ds.api
+                args="const isLoaded = useImagePreloader(images, { delayAfterLoad });"
+                props={{
+                    images: {
+                        description: "List of image URLs.",
+                        type: "string[]",
+                        required: true,
+                    },
+                    delayAfterLoad: {
+                        description: "Extra delay after load completes.",
+                        type: "number",
+                        defaultValue: "0",
+                    },
+                }}
+                returnProps={{
+                    isLoaded: {
+                        description: "True when all images finished loading (or preload completed).",
+                        type: "boolean",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/useImagePreloader/index.js

@@ -0,0 +1,65 @@
+import { useEffect } from "react";
+import { baseStore } from "../baseStore";
+
+export const useImagePreloader = (images = [], options = {}) => {
+    const { delayAfterLoad = 0 } = options;
+    const { isLoaded, set } = baseStore.useLocal({ isLoaded: false });
+
+    useEffect(() => {
+        let cancelled = false;
+
+        if (typeof window === "undefined") {
+            set?.({ isLoaded: true });
+            return;
+        }
+
+        if (!Array.isArray(images) || images.length === 0) {
+            set?.({ isLoaded: true });
+            return;
+        }
+
+        const preload = async () => {
+            try {
+                await Promise.all(
+                    images.filter(Boolean).map(
+                        (src) =>
+                            new Promise((resolve, reject) => {
+                                const img = new window.Image();
+                                img.onload = () => resolve(src);
+                                img.onerror = () => reject(new Error(`Failed to load: ${src}`));
+                                img.src = src;
+                            }),
+                    ),
+                );
+
+                if (cancelled) return;
+
+                if (delayAfterLoad > 0) {
+                    const t = setTimeout(() => {
+                        if (!cancelled) set?.({ isLoaded: true });
+                    }, delayAfterLoad);
+
+                    return () => clearTimeout(t);
+                }
+
+                set?.({ isLoaded: true });
+            } catch (error) {
+                if (cancelled) return;
+                console.error("Error preloading images:", error);
+                set?.({ isLoaded: true });
+            }
+        };
+
+        let cleanupDelay = null;
+        preload().then((maybeCleanup) => {
+            if (typeof maybeCleanup === "function") cleanupDelay = maybeCleanup;
+        });
+
+        return () => {
+            cancelled = true;
+            if (cleanupDelay) cleanupDelay();
+        };
+    }, [set, delayAfterLoad, JSON.stringify(images)]);
+
+    return isLoaded;
+};

package/src/libs/useImagesReady/_dS.jsx

@@ -0,0 +1,51 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { useImagesReady } from ".";
+import { Typo } from "../Typo";
+
+const X = () => {
+    const ready = useImagesReady(() => {}, { selector: "img", includeErrors: true });
+
+    return (
+        <Ds.page
+            title="useImagesReady()"
+            releasedOn="1.0.0"
+            description="Detects when selected DOM images are ready."
+        >
+            <Ds.block
+                title="Watch DOM Images"
+                code={`import { useImagesReady } from "${SYS.basePath}";
+
+                       const isReady = useImagesReady(onReady, { selector: "img", includeErrors: true });`}
+                example={<Typo.span>{`document images ready: ${String(ready)}`}</Typo.span>}
+            />
+            <Ds.api
+                args="const isReady = useImagesReady(fn, { includeErrors, selector });"
+                props={{
+                    fn: {
+                        description: "Called once after images are ready.",
+                        type: "fn",
+                    },
+                    includeErrors: {
+                        description: "Treat errored images as ready.",
+                        type: "boolean",
+                        defaultValue: "true",
+                    },
+                    selector: {
+                        description: "CSS selector for image elements.",
+                        type: "string",
+                        defaultValue: '"img"',
+                    },
+                }}
+                returnProps={{
+                    isReady: {
+                        description: "True once all matched images are considered ready.",
+                        type: "boolean",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/useImagesReady/index.js

@@ -0,0 +1,74 @@
+import { useEffect, useRef } from "react";
+import { baseStore } from "../baseStore";
+
+export const useImagesReady = (fn, options = {}) => {
+    const {
+        selector = "img",
+        includeErrors = true,
+    } = options;
+
+    const { isLoaded, set } = baseStore.useLocal({ isLoaded: false });
+    const fnRef = useRef(fn);
+
+    useEffect(() => {
+        fnRef.current = fn;
+    }, [fn]);
+
+    useEffect(() => {
+        let active = true;
+        const imgs = Array.from(document.querySelectorAll(selector));
+        const isImgDone = (img) => {
+            if (!img.complete) return false;
+            if (includeErrors) return true;
+            return img.naturalWidth > 0;
+        };
+
+        const allDone = () => imgs.every(isImgDone);
+
+        const finishOnce = () => {
+            if (!active) return;
+            active = false;
+            set?.({ isLoaded: true });
+            fnRef.current?.();
+            cleanup();
+        };
+
+        const handlers = new Map();
+
+        const onAny = () => {
+            if (allDone()) finishOnce();
+        };
+
+        const cleanup = () => {
+            for (const [img, handler] of handlers) {
+                img.removeEventListener("load", handler);
+                img.removeEventListener("error", handler);
+            }
+            handlers.clear();
+        };
+
+        if (imgs.length === 0) {
+            finishOnce();
+            return () => {};
+        }
+
+        if (allDone()) {
+            finishOnce();
+            return () => {};
+        }
+
+        for (const img of imgs) {
+            const handler = () => onAny();
+            handlers.set(img, handler);
+            img.addEventListener("load", handler, { passive: true });
+            img.addEventListener("error", handler, { passive: true });
+        }
+
+        return () => {
+            active = false;
+            cleanup();
+        };
+    }, [selector, includeErrors]);
+
+    return isLoaded;
+};

package/src/libs/useMouseXY/_dS.jsx

@@ -0,0 +1,61 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { useMouseXY } from ".";
+import { Typo } from "../Typo";
+import { Flex } from "../Flex";
+import { Button } from "../Button";
+
+const X = () => {
+    const { x, y, manualTrigger } = useMouseXY(80);
+
+    return (
+        <Ds.page
+            title="useMouseXY()"
+            releasedOn="1.0.0"
+            description="Tracks mouse coordinates; updates are coalesced with requestAnimationFrame and an optional minimum interval (delay)."
+        >
+            <Ds.block
+                title="Track Mouse Position"
+                code={`import { useMouseXY } from "${SYS.basePath}";
+
+                       const { x, y, manualTrigger } = useMouseXY(80);`}
+                example={
+                    <Flex.column gap={8}>
+                        <Typo.span>{`x: ${x} y: ${y}`}</Typo.span>
+                        <Button.plain label="manualTrigger()" onClick={manualTrigger} />
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                disableLastBlock
+                args="const { x, y, manualTrigger } = useMouseXY(delay);"
+                props={{
+                    delay: {
+                        description: "Throttle delay in milliseconds.",
+                        type: "number",
+                        defaultValue: "100",
+                    },
+                }}
+            />
+            <Ds.api
+                args="x, y"
+                props={{
+                    x: { description: "Latest mouse X coordinate (clientX).", type: "number" },
+                    y: { description: "Latest mouse Y coordinate (clientY).", type: "number" },
+                }}
+            />
+            <Ds.api
+                args="manualTrigger()"
+                props={{
+                    manualTrigger: {
+                        description:
+                            "Immediately commits the latest known mouse position to state, bypassing throttle delay.",
+                        type: "fn",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/useMouseXY/index.js

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useRef } from "react";
+import { useEventListener } from "../useEventListener";
+import { baseStore } from "../baseStore";
+
+export const useMouseXY = (delay = 100) => {
+    const { x, y, set } = baseStore.useLocal({ x: 0, y: 0 });
+    const latestRef = useRef({ x: 0, y: 0 });
+    const rafRef = useRef(0);
+    const trailingRef = useRef(0);
+    const lastEmitRef = useRef(0);
+
+    const commit = useCallback(() => {
+        rafRef.current = 0;
+        if (trailingRef.current) {
+            clearTimeout(trailingRef.current);
+            trailingRef.current = 0;
+        }
+        lastEmitRef.current = performance.now();
+        const { x: nx, y: ny } = latestRef.current;
+        set?.({ x: nx, y: ny });
+    }, [set]);
+
+    const manualTrigger = useCallback(() => {
+        commit();
+    }, [commit]);
+
+    useEventListener(
+        "mousemove",
+        ({ clientX, clientY }) => {
+            latestRef.current.x = clientX;
+            latestRef.current.y = clientY;
+
+            const scheduleTrailing = (waitMs) => {
+                if (trailingRef.current) return;
+                trailingRef.current = setTimeout(commit, waitMs);
+            };
+
+            const now = performance.now();
+            const elapsed = now - lastEmitRef.current;
+            const canCommitNow = delay <= 0 || elapsed >= delay;
+
+            if (canCommitNow) {
+                if (rafRef.current) return;
+                rafRef.current = requestAnimationFrame(commit);
+                return;
+            }
+
+            scheduleTrailing(delay - elapsed);
+        },
+        { delay: 0, passive: true },
+    );
+
+    useEffect(
+        () => () => {
+            if (rafRef.current) cancelAnimationFrame(rafRef.current);
+            if (trailingRef.current) clearTimeout(trailingRef.current);
+        },
+        [],
+    );
+
+    return { x, y, manualTrigger };
+};

package/src/libs/useObserver/_dS.jsx

@@ -0,0 +1,260 @@
+import { useCallback, useState } from "react";
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { useObserver } from ".";
+import { Typo } from "../Typo";
+import { Flex } from "../Flex";
+import { notifier } from "../notifier";
+
+const ViewportHud = ({ ref1, ref2, ref3, ref4 }) => (
+    <Flex
+        gap={14}
+        padding="10rem 18rem"
+        bgColor="greys.shade20"
+        xAlign="center"
+        yAlign="center"
+        style={{
+            position: "fixed",
+            top: "20rem",
+            left: "50%",
+            transform: "translateX(-50%)",
+            zIndex: 1000,
+            boxShadow: "0 4rem 16rem rgba(0, 0, 0, 0.12)",
+            borderRadius: 8,
+            flexWrap: "wrap",
+            maxWidth: "min(96vw, 640px)",
+        }}
+    >
+        <Typo.span>
+            <b>ref1:</b> {String(ref1)} | <b>ref2:</b> {String(ref2)} | <b>ref3:</b> {String(ref3)}{" "}
+            | <b>ref4:</b> {String(ref4)}
+        </Typo.span>
+    </Flex>
+);
+
+const X = () => {
+    const { ref: ref1, inViewport: inViewport1 } = useObserver({ threshold: 0.2 });
+    const { ref: ref2, inViewport: inViewport2 } = useObserver({ threshold: 0.2 });
+    const { ref: ref3, inViewport: inViewport3 } = useObserver({
+        threshold: 0.2,
+        onEnter: () => notifier.add("ref3 entered viewport."),
+        onExit: () => notifier.add("ref3 exited viewport."),
+    });
+
+    const [scrollRoot, setScrollRoot] = useState(null);
+    const scrollRootRef = useCallback((el) => {
+        setScrollRoot((prev) => (Object.is(prev, el) ? prev : el));
+    }, []);
+
+    const { ref: ref4, inViewport: inViewport4 } = useObserver({
+        customViewport: scrollRoot,
+        customViewportMargin: "-20px",
+        threshold: 0,
+    });
+
+    return (
+        <Ds.page
+            title="useObserver()"
+            releasedOn="1.0.0"
+            description={
+                <>
+                    Wraps the browser <code>IntersectionObserver</code>. By default the browser
+                    viewport is used; pass <code>customViewport</code> to observe inside a
+                    scrollable parent instead. <code>customViewportMargin</code> grows or shrinks
+                    that viewport&apos;s detection box (number = px on all sides, or a CSS margin
+                    string). <code>onEnter</code> / <code>onExit</code> run on crossings;{" "}
+                    <code>inViewport</code> mirrors the latest intersection state for React UI.
+                </>
+            }
+        >
+            <ViewportHud
+                ref1={inViewport1}
+                ref2={inViewport2}
+                ref3={inViewport3}
+                ref4={inViewport4}
+            />
+            <Ds.block
+                title="ref1 — inViewport (viewport root)"
+                code={`import { useObserver } from "${SYS.basePath}";
+
+                       const { ref, inViewport } = useObserver({ threshold: 0.2 });`}
+                example={
+                    <Flex ref={ref1} padding={10} bgColor="greys.shade20">
+                        ref1
+                    </Flex>
+                }
+            />
+            <Ds.block
+                title="ref2 — scroll into view"
+                description="Tall block — scroll the page until ref2 intersects the viewport."
+                example={
+                    <Flex.column gap={8} minHeight={1200} justify="end">
+                        <Flex ref={ref2} padding={10} bgColor="greys.shade20">
+                            ref2
+                        </Flex>
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="ref3 — onEnter / onExit"
+                description="Uses notifier.add on enter and exit. Watch the HUD and toast messages while scrolling ref3 in and out of view."
+                code={`import { notifier } from "${SYS.basePath}";
+
+                       const { ref } = useObserver({
+                        threshold: 0.2,
+                        onEnter: () => notifier.add("ref3 entered viewport."),
+                        onExit: () => notifier.add("ref3 exited viewport."),
+                       });`}
+                example={
+                    <Flex.column gap={8}>
+                        <Flex ref={ref3} padding={10} bgColor="greys.shade20">
+                            ref3
+                        </Flex>
+                    </Flex.column>
+                }
+            />
+            <Ds.block
+                title="ref4 — customViewport & customViewportMargin"
+                description="Scroll inside the box only. ref4 uses the box as customViewport (not the page viewport). customViewportMargin -20px tightens the inner detection zone."
+                code={`const [customViewport, setCustomViewport] = useState(null);
+
+                       const { ref, inViewport } = useObserver({
+                        customViewport,
+                        customViewportMargin: "-20px",
+                        threshold: 0,
+                       });
+
+                       return (
+                        <div ref={setCustomViewport} style={{ height: 200, overflowY: "auto" }}>
+                            <div style={{ minHeight: 480 }} />
+                            <div ref={ref}>ref4</div>
+                        </div>
+                       );`}
+                example={
+                    <Flex.column gap={10} full maxWidth={400}>
+                        <Typo.span size={12}>
+                            Scroll inside this container — the page scroll position does not affect
+                            ref4.
+                        </Typo.span>
+                        <div
+                            ref={scrollRootRef}
+                            style={{
+                                width: "100%",
+                                height: 200,
+                                overflowY: "auto",
+                                overflowX: "hidden",
+                                boxSizing: "border-box",
+                                border: "1px solid #ccc",
+                                borderRadius: 8,
+                                background: "#f5f5f5",
+                            }}
+                        >
+                            <Flex.column gap={8} padding={10} minHeight={520}>
+                                <div style={{ height: 360, flexShrink: 0 }} aria-hidden />
+                                <Flex ref={ref4} padding={10} bgColor="primarys.tint20">
+                                    ref4
+                                </Flex>
+                            </Flex.column>
+                        </div>
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                disableLastBlock
+                args="const { ref, inViewport, phase, direction, intersectionRatio } = useObserver({ disable, onEnter, onExit, customViewport, customViewportMargin, threshold });"
+                props={{
+                    disable: {
+                        description: "Disables observer setup.",
+                        type: "boolean",
+                        defaultValue: "false",
+                    },
+                    onEnter: {
+                        description:
+                            "Called when the element intersects the viewport (per threshold).",
+                        type: "fn",
+                    },
+                    onExit: {
+                        description: "Called when intersection ends.",
+                        type: "fn",
+                    },
+                    customViewport: {
+                        description:
+                            "Custom intersection viewport element. null (default) = browser viewport. Set to a scrollable ancestor to measure visibility inside that container only.",
+                        type: "Element | null",
+                        defaultValue: "null",
+                    },
+                    customViewportMargin: {
+                        description:
+                            'Margin around the custom viewport before intersection is computed. Number = px on all sides; string = CSS margin syntax (e.g. "0px 0px -80px 0px"). Positive expands the zone; negative shrinks it.',
+                        type: "number | string",
+                        defaultValue: "0",
+                    },
+                    threshold: {
+                        description: "Intersection ratio(s) that trigger callbacks (0–1).",
+                        type: "number | number[]",
+                        defaultValue: "0.2",
+                    },
+                }}
+                returnProps={{
+                    ref: {
+                        description: "Ref callback to attach to the observed element.",
+                        type: "fn",
+                    },
+                    inViewport: {
+                        description:
+                            "True when the element intersects the viewport (browser or customViewport) at the given threshold.",
+                        type: "boolean",
+                    },
+                    phase: {
+                        description:
+                            'Current movement phase: "outside", "entering", "inside", or "exiting".',
+                        type: "string",
+                    },
+                    direction: {
+                        description: 'Nearest movement edge: "top", "right", "bottom", or "left".',
+                        type: "string",
+                    },
+                    intersectionRatio: {
+                        description: "Latest visible intersection ratio between 0 and 1.",
+                        type: "number",
+                    },
+                }}
+            />
+            <Ds.api
+                disableLastBlock
+                title="onEnter"
+                args="onEnter(entry);"
+                props={{
+                    entry: {
+                        description: "IntersectionObserverEntry for the crossing.",
+                        type: "IntersectionObserverEntry",
+                    },
+                }}
+            />
+            <Ds.api
+                disableLastBlock
+                title="onExit"
+                args="onExit(entry);"
+                props={{
+                    entry: {
+                        description: "IntersectionObserverEntry for the crossing.",
+                        type: "IntersectionObserverEntry",
+                    },
+                }}
+            />
+            <Ds.api
+                title="ref"
+                args="ref(element);"
+                props={{
+                    element: {
+                        description: "DOM node to observe, or null to unobserve.",
+                        type: "Element | null",
+                        required: true,
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;