@bariskuran/base 0.0.0-stage → 0.0.2

package/src/libs/useSearchParams/_dS.jsx

@@ -0,0 +1,65 @@
+import Ds from "../DesignSystem";
+import { Button } from "../Button";
+
+const X = () => {
+    return (
+        <Ds.page
+            title="useSearchParams()"
+            releasedOn="1.0.0"
+            description={
+                <>
+                    This is the React hook version of manageSearchParams.
+                    <br />
+                    <br />
+                    All core features/options live in{" "}
+                    <Button.string
+                        to="/design-system/manageSearchParams"
+                        label="manageSearchParams"
+                    />
+                    .
+                </>
+            }
+        >
+            <Ds.api
+                disableLastBlock
+                args="const [params, set, clear, raw] = useManageSearchParams({ mapping, defaults, setDefaultsOnMount, disableSetDefaults, replace, maxLength, skipSet, disableBase64, disableTypeControl });"
+                returnProps={{
+                    params: {
+                        description: "Decoded params object returned by manageSearchParams.get().",
+                        type: "object",
+                    },
+                    set: {
+                        description:
+                            "Wrapper for manageSearchParams.set(). Hook options.defaults apply on each set() unless disableSetDefaults is true.",
+                        type: "fn",
+                    },
+                    clear: {
+                        description: "Wrapper for manageSearchParams.clear().",
+                        type: "fn",
+                    },
+                    raw: {
+                        description: "Decoded raw query payload string when available.",
+                        type: "string | undefined",
+                    },
+                }}
+            />
+            <Ds.api
+                title="set"
+                args="set(objOrUpdater, settings);"
+                props={{
+                    objOrUpdater: {
+                        description: "Params object or (currentParams) => nextParams.",
+                        type: "object | fn",
+                        required: true,
+                    },
+                    settings: {
+                        description: "Per-call settings merged with hook options.",
+                        type: "object",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/useSearchParams/index.js

@@ -0,0 +1,32 @@
+import { useMemo, useCallback } from "react";
+import { baseStore } from "../baseStore";
+import { manageSearchParams } from "../manageSearchParams";
+
+export const useManageSearchParams = (options = {}) => {
+    const searchKey = baseStore.useGlobal((s) => s._reactRouterDom?.location?.search ?? "");
+
+    const [params, raw] = useMemo(() => {
+        return manageSearchParams.get(options);
+    }, [searchKey, options]);
+
+    const set = useCallback(
+        (objOrUpdater, settings) => {
+            const next =
+                typeof objOrUpdater === "function"
+                    ? objOrUpdater({ ...(params || {}) })
+                    : objOrUpdater;
+
+            return manageSearchParams.set(next, {
+                ...options,
+                ...settings,
+            });
+        },
+        [options, params],
+    );
+
+    const clear = useCallback((settings) => manageSearchParams.clear({ ...options, ...settings }), [
+        options,
+    ]);
+
+    return useMemo(() => [params || {}, set, clear, raw], [params, set, clear, raw]);
+};

package/src/libs/useTimer/_dS.jsx

@@ -0,0 +1,120 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { getTimersSnapshot, useTimer } from ".";
+import { Typo } from "../Typo";
+import { Button } from "../Button";
+import { Flex } from "../Flex";
+import { baseStore } from "../baseStore";
+import { notifier } from "../notifier";
+
+const X = () => {
+    const { ticks, set } = baseStore.useLocal({ ticks: 0 });
+    const timer = useTimer({
+        timerName: "demoTimer",
+        refreshTime: 2000,
+        loop: true,
+        onStart: () => notifier.add("timer started"),
+        onEnd: () => {
+            notifier.add("timer cycle ended");
+            set((s) => {
+                s.ticks += 1;
+            });
+        },
+    });
+
+    return (
+        <Ds.page
+            title="useTimer()"
+            releasedOn="1.0.0"
+            description="Controllable timer hook with loop and registry support."
+        >
+            <Ds.block
+                title="Start/Stop Loop Timer"
+                description="onStart and onEnd fire notifier toasts on each cycle. refreshTime is 2000ms so the callbacks are easy to observe."
+                code={`import { useTimer } from "${SYS.basePath}";
+                       import { notifier } from "${SYS.basePath}";
+
+                       const { start, stop, isRunning } = useTimer({
+                       refreshTime: 2000,
+                       loop: true,
+                       onStart: () => notifier.add("timer started"),
+                       onEnd: () => notifier.add("timer cycle ended"),
+                       });`}
+                example={
+                    <Flex.column gap={8}>
+                        <Flex gap={8}>
+                            <Button label="Start" onClick={() => timer.start()} />
+                            <Button label="Stop" onClick={() => timer.stop()} />
+                        </Flex>
+                        <Typo.span>{`isRunning: ${String(timer.isRunning)}`}</Typo.span>
+                        <Typo.span>{`ticks: ${ticks}`}</Typo.span>
+                        <Typo.span>{`registry size: ${getTimersSnapshot().length}`}</Typo.span>
+                    </Flex.column>
+                }
+            />
+            <Ds.api
+                disableLastBlock
+                args="const { start, stop, isRunning, timerId, timerName, refreshTime } = useTimer({ loop, onEnd, onStart, refreshTime, startOnLoad, timerName });"
+                props={{
+                    onStart: {
+                        description: "Called when timer starts.",
+                        type: "fn",
+                    },
+                    onEnd: {
+                        description: "Called when timer cycle ends.",
+                        type: "fn",
+                    },
+                    refreshTime: {
+                        description: "Timer duration in ms.",
+                        type: "number",
+                        defaultValue: "1000",
+                    },
+                    loop: {
+                        description: "Restarts automatically.",
+                        type: "boolean",
+                        defaultValue: "true",
+                    },
+                    startOnLoad: {
+                        description: "Starts on mount.",
+                        type: "boolean",
+                        defaultValue: "false",
+                    },
+                    timerName: {
+                        description: "Optional stable timer id/name.",
+                        type: "string",
+                        defaultValue: "generated",
+                    },
+                }}
+                returnProps={{
+                    start: {
+                        description: "Starts or restarts the timer.",
+                        type: "fn",
+                    },
+                    stop: { description: "Stops the timer.", type: "fn" },
+                    isRunning: { description: "True while the timer is active.", type: "boolean" },
+                    timerId: { description: "Stable timer id ref.", type: "ref" },
+                    timerName: { description: "Timer name or id ref.", type: "ref | string" },
+                    refreshTime: { description: "Current refresh interval ref (ms).", type: "ref" },
+                }}
+            />
+            <Ds.api
+                title="start"
+                args="start({ refreshTime, loop });"
+                props={{
+                    refreshTime: {
+                        description:
+                            "Optional interval in milliseconds. When provided, overrides the hook's refreshTime setting for this run.",
+                        type: "number",
+                    },
+                    loop: {
+                        description:
+                            "Optional. When provided, overrides the hook's loop setting for this run.",
+                        type: "boolean",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/useTimer/index.js

@@ -0,0 +1,186 @@
+import { useRef, useEffect, useCallback } from "react";
+import { baseStore } from "../baseStore";
+
+const _timers = new Map();
+const _listeners = new Set();
+
+const _emit = () => {
+    for (const fn of _listeners) {
+        try {
+            fn(getTimersSnapshot());
+        } catch (e) {
+            console.error("Timer registry subscriber error:", e);
+        }
+    }
+};
+
+export const subscribeTimers = (listener) => {
+    if (typeof listener !== "function") return () => {};
+    _listeners.add(listener);
+    return () => _listeners.delete(listener);
+};
+
+export const getTimersSnapshot = () => {
+
+    return Array.from(_timers.values()).map((t) => ({ ...t }));
+};
+
+export const getTimer = (idOrName) => {
+    const key = String(idOrName || "");
+    if (!key) return null;
+
+
+    if (_timers.has(key)) return { ..._timers.get(key) };
+
+
+    for (const t of _timers.values()) {
+        if (t?.timerName === key) return { ...t };
+    }
+    return null;
+};
+
+const _upsertTimer = (meta) => {
+    if (!meta?.timerId) return;
+    _timers.set(meta.timerId, meta);
+    _emit();
+};
+
+const _removeTimer = (timerId) => {
+    if (!timerId) return;
+    _timers.delete(timerId);
+    _emit();
+};
+
+const generateTimerId = () => {
+    if (typeof crypto !== "undefined" && crypto?.randomUUID) return crypto.randomUUID();
+    return `timer_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+};
+
+export const useTimer = (settings = {}) => {
+    const {
+        onStart,
+        onEnd,
+        refreshTime = 1000,
+        loop = true,
+        startOnLoad = false,
+        timerName,
+    } = settings;
+
+    const { isRunning, set } = baseStore.useLocal({ isRunning: false });
+
+    const timerIdRef = useRef(null);
+    if (timerIdRef.current == null) {
+        timerIdRef.current = timerName || generateTimerId();
+    }
+
+    const timeoutRef = useRef(null);
+    const onStartRef = useRef(onStart);
+    const onEndRef = useRef(onEnd);
+    const refreshRef = useRef(refreshTime);
+    const loopRef = useRef(loop);
+    const startRef = useRef(null);
+
+
+    useEffect(() => {
+        onStartRef.current = onStart;
+        onEndRef.current = onEnd;
+        refreshRef.current = refreshTime;
+        loopRef.current = loop;
+
+        _upsertTimer({
+            timerId: timerIdRef.current,
+            timerName: timerName || timerIdRef.current,
+            refreshTime: refreshRef.current,
+            loop: loopRef.current,
+            isRunning: !!isRunning,
+        });
+    }, [onStart, onEnd, refreshTime, loop, timerName, isRunning]);
+
+    useEffect(() => {
+        _upsertTimer({
+            timerId: timerIdRef.current,
+            timerName: timerName || timerIdRef.current,
+            refreshTime: refreshRef.current,
+            loop: loopRef.current,
+            isRunning: !!isRunning,
+        });
+
+        return () => {
+            _removeTimer(timerIdRef.current);
+        };
+    }, []);
+
+    const stop = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+            timeoutRef.current = null;
+        }
+        set?.({ isRunning: false });
+
+        _upsertTimer({
+            timerId: timerIdRef.current,
+            timerName: timerName || timerIdRef.current,
+            refreshTime: refreshRef.current,
+            loop: loopRef.current,
+            isRunning: false,
+        });
+    }, [set, timerName]);
+
+    const start = useCallback(
+        (overrides = {}) => {
+            const { refreshTime: refreshOverride, loop: loopOverride } = overrides;
+
+            if (typeof refreshOverride === "number") refreshRef.current = refreshOverride;
+            if (typeof loopOverride === "boolean") loopRef.current = loopOverride;
+
+            stop();
+
+            set?.({ isRunning: true });
+
+            _upsertTimer({
+                timerId: timerIdRef.current,
+                timerName: timerName || timerIdRef.current,
+                refreshTime: refreshRef.current,
+                loop: loopRef.current,
+                isRunning: true,
+            });
+
+            onStartRef.current?.();
+
+            timeoutRef.current = setTimeout(() => {
+                onEndRef.current?.();
+
+                if (loopRef.current) startRef.current?.();
+                else {
+                    set?.({ isRunning: false });
+                    _upsertTimer({
+                        timerId: timerIdRef.current,
+                        timerName: timerName || timerIdRef.current,
+                        refreshTime: refreshRef.current,
+                        loop: loopRef.current,
+                        isRunning: false,
+                    });
+                }
+            }, refreshRef.current);
+        },
+        [stop, set, timerName],
+    );
+
+    useEffect(() => {
+        startRef.current = start;
+    }, [start]);
+
+    useEffect(() => {
+        if (startOnLoad) start();
+        return () => stop();
+    }, [startOnLoad, start, stop]);
+
+    return {
+        start,
+        stop,
+        isRunning,
+        timerId: timerIdRef,
+        timerName: timerName || timerIdRef,
+        refreshTime: refreshRef,
+    };
+};

package/vite.aliases.mjs

@@ -0,0 +1,43 @@
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const srcRoot = path.join(packageRoot, "src");
+
+const resolveWithExtensions = (basePath) => {
+    const candidates = [
+        basePath,
+        `${basePath}.js`,
+        `${basePath}.jsx`,
+        path.join(basePath, "index.js"),
+        path.join(basePath, "index.jsx"),
+    ];
+    for (const candidate of candidates) {
+        if (fs.existsSync(candidate)) return candidate;
+    }
+    return basePath;
+};
+
+export const bariskuranBaseAliases = () => ({
+    helpers: path.join(srcRoot, "helpers"),
+    libs: path.join(srcRoot, "libs"),
+});
+
+export const bariskuranBaseResolvePlugin = () => ({
+    name: "bariskuran-base-internal-aliases",
+    enforce: "pre",
+    resolveId(source, importer) {
+        if (!importer?.includes("@bariskuran/base")) return null;
+
+        if (source.startsWith("helpers/")) {
+            return resolveWithExtensions(path.join(srcRoot, "helpers", source.slice(8)));
+        }
+
+        if (source.startsWith("libs/")) {
+            return resolveWithExtensions(path.join(srcRoot, "libs", source.slice(5)));
+        }
+
+        return null;
+    },
+});