@bariskuran/base 0.0.0-stage → 0.0.1

package/src/libs/useObserver/index.js

@@ -0,0 +1,239 @@
+import { useEffect, useMemo, useRef, useCallback, useState } from "react";
+import { baseStore } from "../baseStore";
+
+const isRefLike = (value) => value != null && typeof value === "object" && "current" in value;
+const MOVEMENT_EPSILON = 0.001;
+
+const resolveElement = (value) => {
+    if (value == null) return null;
+    if (isRefLike(value)) return value.current ?? null;
+    return value;
+};
+
+const resolveRootBounds = (entry) => {
+    if (entry?.rootBounds) return entry.rootBounds;
+    if (typeof window === "undefined") return null;
+
+    return {
+        top: 0,
+        right: window.innerWidth,
+        bottom: window.innerHeight,
+        left: 0,
+        width: window.innerWidth,
+        height: window.innerHeight,
+    };
+};
+
+export const getObserverDirection = (entry) => {
+    const rect = entry?.boundingClientRect;
+    const rootBounds = resolveRootBounds(entry);
+    if (!rect || !rootBounds) return "bottom";
+
+    const overflow = {
+        top: Math.max(0, rootBounds.top - rect.top),
+        right: Math.max(0, rect.right - rootBounds.right),
+        bottom: Math.max(0, rect.bottom - rootBounds.bottom),
+        left: Math.max(0, rootBounds.left - rect.left),
+    };
+    const horizontalOverflow = Math.max(overflow.left, overflow.right);
+    const verticalOverflow = Math.max(overflow.top, overflow.bottom);
+
+    if (horizontalOverflow > verticalOverflow && horizontalOverflow > 0) {
+        return overflow.left > overflow.right ? "left" : "right";
+    }
+
+    const rootCenterY = rootBounds.top + rootBounds.height / 2;
+    const rectCenterY = rect.top + rect.height / 2;
+    return rectCenterY < rootCenterY ? "top" : "bottom";
+};
+
+export const getObserverPhase = ({ entry, previousRatio = 0, previousIntersecting = false }) => {
+    const ratio = entry?.intersectionRatio ?? 0;
+    const isIntersecting = Boolean(entry?.isIntersecting);
+
+    if (!isIntersecting) return "outside";
+    if (!previousIntersecting) return "entering";
+    if (ratio < previousRatio - MOVEMENT_EPSILON) return "exiting";
+    if (ratio >= 0.99) return "inside";
+    if (ratio > previousRatio + MOVEMENT_EPSILON) return "entering";
+    return "inside";
+};
+
+export const useObserver = (options = {}) => {
+    const wantsCustomViewport = "customViewport" in options || "root" in options;
+
+    const {
+        onEnter,
+        onExit,
+        threshold = 0.2,
+        customViewportMargin: customViewportMarginOption,
+        rootMargin: rootMarginOption,
+        customViewport: customViewportOption = null,
+        root: rootOption = null,
+        disable = false,
+    } = options;
+
+    const customViewport = customViewportOption ?? rootOption ?? null;
+    const customViewportMargin = customViewportMarginOption ?? rootMarginOption ?? 0;
+
+    const supportsIO = typeof window !== "undefined" && typeof IntersectionObserver !== "undefined";
+
+    const { inViewport, phase, direction, intersectionRatio, set } = baseStore.useLocal({
+        inViewport: supportsIO ? false : true,
+        phase: supportsIO ? "outside" : "inside",
+        direction: "bottom",
+        intersectionRatio: supportsIO ? 0 : 1,
+    });
+
+    const setRef = useRef(set);
+    setRef.current = set;
+
+    const nodeRef = useRef(null);
+    const [observedNode, setObservedNode] = useState(null);
+
+    const onEnterRef = useRef(onEnter);
+    const onExitRef = useRef(onExit);
+    const previousEntryRef = useRef({
+        isIntersecting: false,
+        intersectionRatio: 0,
+    });
+
+    useEffect(() => {
+        onEnterRef.current = onEnter;
+        onExitRef.current = onExit;
+    }, [onEnter, onExit]);
+
+    const ref = useCallback((el) => {
+        if (Object.is(nodeRef.current, el)) return;
+        nodeRef.current = el;
+        setObservedNode(el);
+    }, []);
+
+    useEffect(() => {
+        if (disable) return;
+        if (!supportsIO) return;
+
+        const node = observedNode;
+        if (!node) return;
+
+        const root = resolveElement(customViewport);
+
+        if (wantsCustomViewport && !root) return;
+
+        const margin =
+            typeof customViewportMargin === "number"
+                ? `${customViewportMargin}px`
+                : String(customViewportMargin);
+
+        const observerOptions = { threshold, rootMargin: margin };
+        if (root) observerOptions.root = root;
+
+        // Remount / HMR: don't carry a stale "already intersecting" flag into a fresh observer.
+        previousEntryRef.current = {
+            isIntersecting: false,
+            intersectionRatio: 0,
+        };
+
+        const applyEntry = (entry) => {
+            if (!entry) return;
+
+            const isIn = !!entry.isIntersecting;
+            const previousEntry = previousEntryRef.current;
+            const nextPhase = getObserverPhase({
+                entry,
+                previousRatio: previousEntry.intersectionRatio,
+                previousIntersecting: previousEntry.isIntersecting,
+            });
+            const nextDirection = getObserverDirection(entry);
+
+            setRef.current?.((d) => {
+                d.inViewport = isIn;
+                d.phase = nextPhase;
+                d.direction = nextDirection;
+                d.intersectionRatio = entry.intersectionRatio ?? 0;
+            });
+
+            if (isIn && !previousEntry.isIntersecting) onEnterRef.current?.(entry);
+            if (!isIn && previousEntry.isIntersecting) onExitRef.current?.(entry);
+
+            previousEntryRef.current = {
+                isIntersecting: isIn,
+                intersectionRatio: entry.intersectionRatio ?? 0,
+            };
+        };
+
+        const observer = new IntersectionObserver(([entry]) => {
+            applyEntry(entry);
+        }, observerOptions);
+
+        observer.observe(node);
+
+        // IO callbacks are async. After HMR/remount, the first callback can be skipped while the
+        // node is already on screen — ScrollAnimatedItem would stay at opacity 0 until a refresh.
+        const pending = observer.takeRecords?.() || [];
+        if (pending.length > 0) {
+            applyEntry(pending[pending.length - 1]);
+        }
+
+        let rafId = 0;
+        if (!previousEntryRef.current.isIntersecting) {
+            rafId = requestAnimationFrame(() => {
+                const latePending = observer.takeRecords?.() || [];
+                if (latePending.length > 0) {
+                    applyEntry(latePending[latePending.length - 1]);
+                    return;
+                }
+
+                if (previousEntryRef.current.isIntersecting) return;
+
+                const rect = node.getBoundingClientRect();
+                const rootRect = root?.getBoundingClientRect?.() || {
+                    top: 0,
+                    left: 0,
+                    right: window.innerWidth,
+                    bottom: window.innerHeight,
+                    width: window.innerWidth,
+                    height: window.innerHeight,
+                };
+                const isIn =
+                    rect.bottom > rootRect.top &&
+                    rect.right > rootRect.left &&
+                    rect.top < rootRect.bottom &&
+                    rect.left < rootRect.right;
+
+                if (!isIn) return;
+
+                applyEntry({
+                    isIntersecting: true,
+                    intersectionRatio: 1,
+                    boundingClientRect: rect,
+                    rootBounds: rootRect,
+                });
+            });
+        }
+
+        return () => {
+            if (rafId) cancelAnimationFrame(rafId);
+            observer.disconnect();
+        };
+    }, [
+        supportsIO,
+        observedNode,
+        threshold,
+        customViewportMargin,
+        customViewport,
+        wantsCustomViewport,
+        disable,
+    ]);
+
+    return useMemo(
+        () => ({
+            ref,
+            inViewport: !!inViewport,
+            phase,
+            direction,
+            intersectionRatio,
+        }),
+        [ref, inViewport, phase, direction, intersectionRatio],
+    );
+};

package/src/libs/useObserver/index.test.js

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import { getObserverDirection, getObserverPhase } from ".";
+
+const rootBounds = {
+    top: 0,
+    right: 1000,
+    bottom: 800,
+    left: 0,
+    width: 1000,
+    height: 800,
+};
+
+const createEntry = ({
+    isIntersecting = true,
+    intersectionRatio = 0.5,
+    top = 300,
+    left = 400,
+    width = 200,
+    height = 200,
+} = {}) => ({
+    isIntersecting,
+    intersectionRatio,
+    rootBounds,
+    boundingClientRect: {
+        top,
+        right: left + width,
+        bottom: top + height,
+        left,
+        width,
+        height,
+    },
+});
+
+describe("useObserver motion helpers", () => {
+    it("distinguishes entering, inside, exiting, and outside phases", () => {
+        expect(
+            getObserverPhase({
+                entry: createEntry({ intersectionRatio: 0.2 }),
+                previousRatio: 0,
+                previousIntersecting: false,
+            }),
+        ).toBe("entering");
+        expect(
+            getObserverPhase({
+                entry: createEntry({ intersectionRatio: 1 }),
+                previousRatio: 0.8,
+                previousIntersecting: true,
+            }),
+        ).toBe("inside");
+        expect(
+            getObserverPhase({
+                entry: createEntry({ intersectionRatio: 0.3 }),
+                previousRatio: 0.5,
+                previousIntersecting: true,
+            }),
+        ).toBe("exiting");
+        expect(
+            getObserverPhase({
+                entry: createEntry({ isIntersecting: false, intersectionRatio: 0 }),
+                previousRatio: 0.2,
+                previousIntersecting: true,
+            }),
+        ).toBe("outside");
+    });
+
+    it("resolves the viewport edge nearest to the observed item", () => {
+        expect(getObserverDirection(createEntry({ top: -120 }))).toBe("top");
+        expect(getObserverDirection(createEntry({ top: 720 }))).toBe("bottom");
+        expect(getObserverDirection(createEntry({ top: 300, left: -180 }))).toBe("left");
+        expect(getObserverDirection(createEntry({ top: 300, left: 980 }))).toBe("right");
+    });
+});

package/src/libs/usePrevious/_dS.jsx

@@ -0,0 +1,99 @@
+import { useEffect } from "react";
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { usePrevious } from ".";
+import { Button } from "../Button";
+import { Typo } from "../Typo";
+import { Flex } from "../Flex";
+import { baseStore } from "../baseStore";
+
+const X = () => {
+    const { count, set } = baseStore.useLocal({ count: 0 });
+    const { previousValue: prevCount, onChange } = usePrevious(count);
+
+    useEffect(
+        () =>
+            onChange(({ previousValue, currentValue }) => {
+                console.log("count changed from", previousValue, "to", currentValue);
+            }),
+        [onChange],
+    );
+
+    return (
+        <Ds.page
+            title="usePrevious()"
+            releasedOn="1.0.0"
+            description="Keeps previous render value."
+        >
+            <Ds.block
+                title="Previous Value Tracking"
+                code={`import { usePrevious, baseStore } from "${SYS.basePath}";
+
+                       const { count, set } = baseStore.useLocal({ count: 0 });
+                       const { previousValue, setPreviousValue, onChange } = usePrevious(count);
+
+                       onChange(({ previousValue, currentValue }) => {
+                       console.log("count changed from", previousValue, "to", currentValue);
+                       });`}
+                example={
+                    <Flex.column gap={8}>
+                        <Button.plain
+                            label="add +1"
+                            skipClickCooldown
+                            skipOnClickHold
+                            onClick={() =>
+                                set((s) => {
+                                    s.count += 1;
+                                })
+                            }
+                        />
+                        <Typo.span>
+                            count changed from {String(prevCount)} to {count}
+                        </Typo.span>
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                disableLastBlock
+                args="const { previousValue, setPreviousValue, onChange } = usePrevious(value);"
+                props={{
+                    value: {
+                        description: "Current value to track.",
+                        type: "any",
+                        required: true,
+                    },
+                }}
+                returnProps={{
+                    previousValue: {
+                        description: "Value from the previous render.",
+                        type: "any",
+                    },
+                    setPreviousValue: {
+                        description: "Manually sets the stored previous value.",
+                        type: "fn",
+                    },
+                    onChange: {
+                        description: "Registers a change listener.",
+                        type: "fn",
+                    },
+                }}
+            />
+            <Ds.api
+                title="onChange"
+                args="onChange(({ previousValue, currentValue }) => {});"
+                props={{
+                    previousValue: {
+                        description: "Value from the previous render.",
+                        type: "any",
+                    },
+                    currentValue: {
+                        description: "Current value after the change.",
+                        type: "any",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/usePrevious/index.js

@@ -0,0 +1,37 @@
+import { useCallback, useEffect, useRef } from "react";
+
+export const usePrevious = (value) => {
+    const ref = useRef(undefined);
+    const listenersRef = useRef(new Set());
+
+    const setPreviousValue = useCallback((next) => {
+        ref.current = next;
+    }, []);
+
+    const onChange = useCallback((callback) => {
+        if (typeof callback !== "function") return () => {};
+        listenersRef.current.add(callback);
+        return () => {
+            listenersRef.current.delete(callback);
+        };
+    }, []);
+
+    const previousValue = ref.current;
+
+    useEffect(() => {
+        if (previousValue !== value) {
+            const payload = { previousValue, currentValue: value };
+            listenersRef.current.forEach((callback) => {
+                try {
+                    callback(payload);
+                } catch (error) {
+                    console.error("usePrevious onChange listener error:", error);
+                }
+            });
+        }
+    }, [value, previousValue]);
+
+    ref.current = value;
+
+    return { previousValue, setPreviousValue, onChange };
+};

package/src/libs/useRevealNavItem/_dS.jsx

@@ -0,0 +1,129 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="useRevealNavItem()"
+        releasedOn="1.0.0"
+        description={
+            <>
+                Reads the current route from React Router (useLocation), matches it to a nav item,
+                attaches a ref on the active row, and scrolls it into view when the pathname or link
+                list changes.
+                <br />
+                <br />
+                Used in the Design System Layout sidebar — open any page from the left navigation to
+                see it live. Must run under a Router (same as Design System Layout).
+            </>
+        }
+    >
+        <Ds.block
+            title="Basic usage"
+            code={`import { useRevealNavItem } from "${SYS.basePath}";
+
+                   const [isActive, activeNavItemRef] = useRevealNavItem({
+                    links: navItems,
+                    basePath: "/",
+                    getPathFromLink: (link) => link[1],
+                   });
+
+                   {navItems.map((entry) => {
+                    const [name, path] = entry;
+                    const isActive = isActive(entry);
+                    return (
+                        <Button
+                            key={path}
+                            ref={isActive ? activeNavItemRef : undefined}
+                            to={path}
+                            activeManually={isActive}
+                            // ...other Button props
+                        />
+                    );
+                   })}`}
+        />
+        <Ds.api
+            disableLastBlock
+            args="const [isActive, activeNavItemRef] = useRevealNavItem({ pathname, links, basePath, getPathFromLink, block, inline, behavior, extraDeps });"
+            props={{
+                pathname: {
+                    description:
+                        "Optional pathname override. Default: useLocation().pathname (hook must run inside a Router).",
+                    type: "string",
+                },
+                links: {
+                    description:
+                        "Nav items list; used for isActive matching and scroll effect deps.",
+                    type: "array",
+                    defaultValue: "[]",
+                },
+                basePath: {
+                    description: "URL base when path segment is empty (index route).",
+                    type: "string",
+                    defaultValue: '"/design-system"',
+                },
+                getPathFromLink: {
+                    description: "Maps a link item to a path segment; default is link[1].",
+                    type: "fn",
+                    defaultValue: "link => link[1]",
+                },
+                block: {
+                    description: "scrollIntoView block option.",
+                    type: "string",
+                    defaultValue: '"center"',
+                },
+                inline: {
+                    description: "scrollIntoView inline option.",
+                    type: "string",
+                    defaultValue: '"nearest"',
+                },
+                behavior: {
+                    description: "scrollIntoView behavior.",
+                    type: "string",
+                    defaultValue: '"smooth"',
+                },
+                extraDeps: {
+                    description: "Extra useLayoutEffect dependency values.",
+                    type: "array",
+                    defaultValue: "[]",
+                },
+            }}
+            returnProps={{
+                isActive: {
+                    description:
+                        "Predicate: true when the item matches the current pathname under basePath.",
+                    type: "fn",
+                },
+                activeNavItemRef: {
+                    description:
+                        "Ref to attach to the active nav element; triggers scrollIntoView when pathname changes.",
+                    type: "ref",
+                },
+            }}
+        />
+        <Ds.api
+            disableLastBlock
+            title="getPathFromLink"
+            args="getPathFromLink(link);"
+            props={{
+                link: {
+                    description: "Nav entry tuple (name, path, …).",
+                    type: "array",
+                    required: true,
+                },
+            }}
+        />
+        <Ds.api
+            title="isActive"
+            args="isActive(item);"
+            props={{
+                item: {
+                    description: "Nav entry tuple (name, path, …).",
+                    type: "array",
+                    required: true,
+                },
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/useRevealNavItem/index.js

@@ -0,0 +1,96 @@
+import { useCallback, useLayoutEffect, useRef } from "react";
+import { useLocation } from "react-router-dom";
+
+const normalizePathname = (pathname) =>
+    pathname.length > 1 && pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+
+const hrefUnderBase = (basePath, pathSegment) => {
+    const base = String(basePath ?? "/").replace(/\/+$/, "") || "/";
+    if (pathSegment == null || pathSegment === "") return base;
+    const seg = String(pathSegment).replace(/^\//, "");
+    return `${base}/${seg}`;
+};
+
+const scrollWithinParent = (el, scrollParent, { block, behavior }) => {
+    const elRect = el.getBoundingClientRect();
+    const parentRect = scrollParent.getBoundingClientRect();
+
+    let delta = 0;
+
+    if (block === "center") {
+        delta = elRect.top - parentRect.top - (parentRect.height - elRect.height) / 2;
+    } else if (block === "start") {
+        delta = elRect.top - parentRect.top;
+    } else if (block === "end") {
+        delta = elRect.bottom - parentRect.bottom;
+    } else if (elRect.top < parentRect.top) {
+        delta = elRect.top - parentRect.top;
+    } else if (elRect.bottom > parentRect.bottom) {
+        delta = elRect.bottom - parentRect.bottom;
+    } else {
+        return;
+    }
+
+    if (Math.abs(delta) < 1) return;
+
+    const maxScroll = Math.max(0, scrollParent.scrollHeight - scrollParent.clientHeight);
+    const nextScrollTop = Math.min(maxScroll, Math.max(0, scrollParent.scrollTop + delta));
+
+    if (behavior === "smooth") {
+        scrollParent.scrollTo({ top: nextScrollTop, behavior: "smooth" });
+        return;
+    }
+
+    scrollParent.scrollTop = nextScrollTop;
+};
+
+const revealNavItem = (el, { scrollRootRef, block, inline, behavior }) => {
+    const scrollRoot = scrollRootRef?.current;
+
+    if (scrollRoot) {
+        scrollWithinParent(el, scrollRoot, { block, behavior });
+        return;
+    }
+
+    el.scrollIntoView({ block, inline, behavior });
+};
+
+export const useRevealNavItem = ({
+    pathname: pathnameOverride,
+    links = [],
+    basePath = "/",
+    getPathFromLink = (link) => link[1],
+    scrollRootRef,
+    block = "center",
+    inline = "nearest",
+    behavior = "smooth",
+    extraDeps = [],
+}) => {
+    const { pathname: routePathname } = useLocation();
+    const pathname = pathnameOverride ?? routePathname;
+    const activeNavItemRef = useRef(null);
+
+    const isActive = useCallback(
+        (item) => {
+            const seg = getPathFromLink(item);
+            const href = hrefUnderBase(basePath, seg);
+            return normalizePathname(pathname) === normalizePathname(href);
+        },
+        [pathname, basePath, getPathFromLink],
+    );
+
+    useLayoutEffect(() => {
+        const el = activeNavItemRef.current;
+        if (!el) return;
+
+        const run = () => revealNavItem(el, { scrollRootRef, block, inline, behavior });
+
+        run();
+
+        const raf = requestAnimationFrame(run);
+
+        return () => cancelAnimationFrame(raf);
+    }, [pathname, links, scrollRootRef, block, inline, behavior, basePath, getPathFromLink, ...extraDeps]);
+
+    return [isActive, activeNavItemRef];
+};