@bariskuran/base 0.0.0-stage → 0.0.2

package/src/libs/cssNormalizeSize/_dS.jsx

@@ -0,0 +1,49 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="cssNormalizeSize()"
+        releasedOn="1.0.0"
+        description="Internal helper for normalizing size-like values into CSS-safe output."
+    >
+        <Ds.block
+            title="How it works (quick reminder)"
+            code={`import { cssNormalizeSize } from "${SYS.basePath}";
+
+                    cssNormalizeSize(12);         // "12rem"
+                    cssNormalizeSize("12");       // "12rem"
+                    cssNormalizeSize("12px");     // "12px"
+                    cssNormalizeSize(" 1.5 rem "); // "1.5rem" (spaces normalized)
+                    cssNormalizeSize(0);          // 0
+                    cssNormalizeSize(null);       // undefined`}
+            description={`This function is used by internal styling utilities.
+
+                    Rules:
+                    - null/undefined -> undefined
+                    - 0/"0" -> 0 (unitless zero)
+                    - number -> "<n>rem"
+                    - numeric string -> "<n>rem"
+                    - already-unit strings (px, rem, em, %, vw, vh, etc.) stay as-is
+                    - unknown strings are returned after trimming whitespace`}
+        />
+        <Ds.api
+            args="const size = cssNormalizeSize(value);"
+            props={{
+                value: {
+                    description: "Any potential css size input.",
+                    type: "any",
+                    required: true,
+                },
+            }}
+            returnProps={{
+                size: {
+                    description: "Normalized CSS size value, or undefined for missing input.",
+                    type: "string | number | undefined",
+                },
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/cssNormalizeSize/index.js

@@ -0,0 +1,30 @@
+export const cssNormalizeSize = (value) => {
+    if (value == null) return undefined;
+
+    if (value === 0 || value === "0") return 0;
+
+    if (typeof value === "number") {
+        return `${value}rem`;
+    }
+
+    if (typeof value === "string") {
+        let v = value.trim();
+        v = v.replace(/\s+/g, "");
+
+        if (/^0+(\.0+)?$/.test(v)) {
+            return 0;
+        }
+
+        if (/^\d+(\.\d+)?$/.test(v)) {
+            return `${v}rem`;
+        }
+
+        if (/^\d+(\.\d+)?(px|rem|em|%|vw|vh|vmin|vmax|dvw|dvh)$/.test(v)) {
+            return v;
+        }
+
+        return v;
+    }
+
+    return value;
+};

package/src/libs/cssSpacingResolver/_dS.jsx

@@ -0,0 +1,57 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="cssSpacingResolver()"
+        releasedOn="1.0.0"
+        description="Internal helper that resolves margin/padding shorthands + side overrides into a 4-side CSS string."
+    >
+        <Ds.block
+            title="How it works (quick reminder)"
+            code={`import { cssSpacingResolver } from "${SYS.basePath}";
+
+                    cssSpacingResolver({ margin: "10 20" });
+                    // "10rem 20rem 10rem 20rem"
+
+                    cssSpacingResolver({ margin: "10px", marginLeft: "5px" });
+                    // "10px 10px 10px 5px"
+
+                    cssSpacingResolver({ padding: "4 8", paddingTop: "20" }, "padding");
+                    // "20rem 8rem 4rem 8rem"`}
+            description={`Used internally by layout/styling helpers.
+
+                    Flow:
+                    - reads base shorthand from props[key] (default key = "margin")
+                    - expands 1/2/3/4-value shorthand to top/right/bottom/left
+                    - applies side-specific overrides (e.g. marginTop, marginLeft, kebab-case too)
+                    - normalizes each side via cssNormalizeSize
+                    - returns final "top right bottom left" string
+                    - if all sides are missing, returns null`}
+        />
+        <Ds.api
+            args='const spacing = cssSpacingResolver(props, key);'
+            props={{
+                props: {
+                    description: "Object that may contain shorthand + side spacing fields.",
+                    type: "object",
+                    required: true,
+                },
+                key: {
+                    description: 'Base key to resolve ("margin" or "padding", etc.).',
+                    type: "string",
+                    defaultValue: '"margin"',
+                },
+            }}
+            returnProps={{
+                spacing: {
+                    description:
+                        'Normalized "top right bottom left" CSS spacing string, or null when all sides are missing.',
+                    type: "string | null",
+                },
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/cssSpacingResolver/index.js

@@ -0,0 +1,51 @@
+import { cssNormalizeSize } from "../cssNormalizeSize";
+
+const parseSpacing = (value) => {
+    if (value == null) return {};
+
+    if (typeof value === "number" || typeof value === "string") {
+        const parts = String(value).trim().split(/\s+/);
+
+        const [t, r = t, b = t, l = r] =
+            parts.length === 1
+                ? [parts[0], parts[0], parts[0], parts[0]]
+                : parts.length === 2
+                  ? [parts[0], parts[1], parts[0], parts[1]]
+                  : parts.length === 3
+                    ? [parts[0], parts[1], parts[2], parts[1]]
+                    : parts.length >= 4
+                      ? [parts[0], parts[1], parts[2], parts[3]]
+                      : [];
+
+        return {
+            top: cssNormalizeSize(t),
+            right: cssNormalizeSize(r),
+            bottom: cssNormalizeSize(b),
+            left: cssNormalizeSize(l),
+        };
+    }
+
+    if (typeof value === "object") {
+        return {
+            top: cssNormalizeSize(value.top),
+            right: cssNormalizeSize(value.right),
+            bottom: cssNormalizeSize(value.bottom),
+            left: cssNormalizeSize(value.left),
+        };
+    }
+
+    return {};
+};
+
+export const cssSpacingResolver = (props = {}, key = "margin") => {
+    const base = parseSpacing(props[key]);
+
+    const top = cssNormalizeSize(props[`${key}Top`] ?? props[`${key}-top`] ?? base.top);
+    const right = cssNormalizeSize(props[`${key}Right`] ?? props[`${key}-right`] ?? base.right);
+    const bottom = cssNormalizeSize(props[`${key}Bottom`] ?? props[`${key}-bottom`] ?? base.bottom);
+    const left = cssNormalizeSize(props[`${key}Left`] ?? props[`${key}-left`] ?? base.left);
+
+    if ([top, right, bottom, left].every((v) => v == null)) return null;
+
+    return `${top || 0} ${right || 0} ${bottom || 0} ${left || 0}`;
+};

package/src/libs/debouncedFunction/_dS.jsx

@@ -0,0 +1,308 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { debouncedFunction } from ".";
+import { Button } from "../Button";
+import { Flex } from "../Flex";
+import { Typo } from "../Typo";
+import { baseStore } from "../baseStore";
+import { notifier } from "../notifier";
+import { t } from "../getText";
+
+const X = () => {
+    const { count, throttleCount, set, ex2, ex3, ex4, ex5 } = baseStore.useLocal({
+        count: 0,
+        throttleCount: 0,
+        ex2: 0,
+        ex3: 0,
+        ex4: 0,
+        ex5: 0,
+    });
+
+    const runDebounced = debouncedFunction(
+        () =>
+            set((s) => {
+                s.count += 1;
+            }),
+        { delay: 1000 },
+    );
+
+    const runThrottle = debouncedFunction(
+        () =>
+            set((s) => {
+                s.throttleCount += 1;
+            }),
+        {
+            delay: 1000,
+            isThrottle: true,
+        },
+    );
+
+    const runEx2 = debouncedFunction(
+        () =>
+            set((s) => {
+                s.ex2 += 1;
+            }),
+        { delay: 1000, getFirst: true, functionName: "example2" },
+    );
+
+    const runEx3 = debouncedFunction(
+        () =>
+            set((s) => {
+                s.ex3 += 1;
+            }),
+        { delay: 1000, getFirst: true, functionName: "example3", isThrottle: true },
+    );
+
+    const runEx4 = debouncedFunction(
+        () =>
+            set((s) => {
+                s.ex4 += 1;
+            }),
+        {
+            delay: 2000,
+            onStart: () => notifier.add("Debounced onStart called."),
+            onEnd: () => notifier.add("Debounced onEnd called."),
+        },
+    );
+
+    const runEx5 = debouncedFunction(
+        () =>
+            set((s) => {
+                s.ex5 += 1;
+            }),
+        {
+            delay: 2000,
+            isThrottle: true,
+            onStart: () => notifier.add("Throttled onStart called."),
+            onEnd: () => notifier.add("Throttled onEnd called."),
+        },
+    );
+
+    return (
+        <Ds.page
+            title="debouncedFunction()"
+            releasedOn="1.0.0"
+            description={
+                <>
+                    {t({
+                        tr: "Debounce veya throttle davranışına sahip fonksiyon sarmalayıcıları oluşturur.",
+                        en: "Creates function wrappers with debounce or throttle behaviour.",
+                    })}
+                    <br />
+                    <br />
+                    {t({ tr: "Hook kullanımını görmek için ", en: "See " })}
+                    <Button.string
+                        to="/design-system/useDebouncedFunction"
+                        label="useDebouncedFunction"
+                    />{" "}
+                    {t({ tr: " sayfasına bakın.", en: " for hook usage." })}
+                </>
+            }
+        >
+            <Ds.block
+                title={{ tr: "Temel Debounce ve Throttle", en: "Basic Debounce & Throttle" }}
+                code={`import { debouncedFunction } from "${SYS.basePath}";
+
+                        const debounced = debouncedFunction(callback, {
+                            delay: 1000
+                        });
+                        debounced();
+
+                        const throttled = debouncedFunction(callback, {
+                          delay: 1000,
+                          isThrottle: true,
+                        });
+                        throttled();`}
+                example={
+                    <Flex gap={10}>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="Debounced"
+                                onClick={runDebounced}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${count}`} />
+                        </Flex.column>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="Throttled"
+                                onClick={runThrottle}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${throttleCount}`} />
+                        </Flex.column>
+                    </Flex>
+                }
+            />
+            <Ds.block
+                title="getFirst & functionName"
+                description={{
+                    tr: "getFirst: İlk çağrı penceresinde fonksiyonu hemen tetikler. Yalnızca debounce modunda çalışır.\n\nfunctionName: Dahili debounce durumu için ortak anahtar. Bazı durumlarda aynı fonksiyonun birden fazla örneğinin aynı debounce/throttle kilidini paylaşmasını isteyebilirsiniz. Varsayılan olarak fonksiyon referansından otomatik üretilir; gerektiğinde benzersiz bir anahtar verebilirsiniz.",
+                    en: "getFirst: Triggers immediately in the first call window. Works only in debounce mode.\n\nfunctionName: A shared key for internal debounce state. In some cases you may want multiple instances of the same function to share the same debounce/throttle lock. It is generated automatically from the function reference by default, but you can provide a unique key when needed.",
+                }}
+                code={`import { debouncedFunction } from "${SYS.basePath}";
+
+                        const example2 = debouncedFunction(callback, {
+                            delay: 1000,
+                            getFirst: true,
+                            functionName: "example2"
+                        });
+
+                        example2();`}
+                example={
+                    <Flex gap={10}>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="getFirst"
+                                onClick={runEx2}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${ex2}`} />
+                        </Flex.column>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="functionName"
+                                onClick={runEx3}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${ex3}`} />
+                        </Flex.column>
+                    </Flex>
+                }
+            />
+            <Ds.block
+                title="onStart & onEnd"
+                description={{
+                    tr: "onStart: Bekleme penceresi başladığında çağrılır.\n\nonEnd: Bekleme penceresi sona erdiğinde çağrılır.",
+                    en: "onStart: Called when the wait window starts.\n\nonEnd: Called when the wait window ends.",
+                }}
+                code={`import { debouncedFunction } from "${SYS.basePath}";
+
+                        const example4 = debouncedFunction(
+                             () =>
+                                 set((s) => {
+                                     s.ex4 += 1;
+                                 }),
+                             {
+                                 delay: 2000,
+                                 onStart: () => notifier.add("Debounced onStart called."),
+                                 onEnd: () => notifier.add("Debounced onEnd called."),
+                             },
+                         );
+
+                         const example5 = debouncedFunction(
+                             () =>
+                                 set((s) => {
+                                     s.ex5 += 1;
+                                 }),
+                             {
+                                 delay: 2000,
+                                 isThrottle: true,
+                                 onStart: () => notifier.add("Throttled onStart called."),
+                                 onEnd: () => notifier.add("Throttled onEnd called."),
+                             },
+                         );
+
+                        example4();
+                        example5();`}
+                example={
+                    <Flex gap={10}>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="Debounced onStart & onEnd"
+                                onClick={runEx4}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${ex4}`} />
+                        </Flex.column>
+                        <Flex.column gap={10}>
+                            <Button.plain
+                                label="Throttled onStart & onEnd"
+                                onClick={runEx5}
+                                skipClickCooldown
+                                skipOnClickHold
+                            />
+                            <Typo.span children={`Count: ${ex5}`} />
+                        </Flex.column>
+                    </Flex>
+                }
+            />
+            <Ds.api
+                disableLastBlock
+                args="const debounced = debouncedFunction(fn, { delay, functionName, getFirst, isThrottle, onEnd, onStart });"
+                props={{
+                    fn: {
+                        description: { tr: "Sarmalanacak fonksiyon.", en: "Function to wrap." },
+                        type: "fn",
+                        required: true,
+                    },
+                    delay: {
+                        description: { tr: "Milisaniye cinsinden bekleme süresi.", en: "Wait duration in milliseconds." },
+                        type: "number",
+                        defaultValue: "500",
+                    },
+                    isThrottle: {
+                        description: { tr: "Throttle davranışını etkinleştirir.", en: "Switches to throttle behavior." },
+                        type: "boolean",
+                        defaultValue: "false",
+                    },
+                    getFirst: {
+                        description: {
+                            tr: "İlk çağrı penceresinde hemen tetikler (throttle modunda yok sayılır).",
+                            en: "Triggers immediately in the first call window (ignored in throttle mode).",
+                        },
+                        type: "boolean",
+                        defaultValue: "false",
+                    },
+                    functionName: {
+                        description: { tr: "Dahili debounce durumu için ortak anahtar.", en: "Shared key for internal debounce state." },
+                        type: "string",
+                        defaultValue: "auto-generated per function reference",
+                    },
+                    onStart: {
+                        description: { tr: "Bekleme penceresi başladığında çağrılır.", en: "Called when the wait window starts." },
+                        type: "fn",
+                    },
+                    onEnd: {
+                        description: { tr: "Bekleme penceresi bittiğinde çağrılır.", en: "Called when the wait window ends." },
+                        type: "fn",
+                    },
+                }}
+                returnProps={{
+                    debounced: {
+                        description: { tr: "Debounce veya throttle uygulanmış sarmalayıcı; fn ile aynı argümanlarla çağrılır.", en: "Debounced or throttled wrapper; call with the same args as fn." },
+                        type: "fn",
+                    },
+                }}
+            />
+            <Ds.api
+                disableLastBlock
+                title="onStart"
+                args="onStart(...args);"
+                props={{
+                    args: {
+                        description: { tr: "Debounce/throttle çağrısına iletilen aynı argümanlar.", en: "Same arguments passed to the debounced/throttled call." },
+                        type: "any[]",
+                    },
+                }}
+            />
+            <Ds.api
+                title="debounced"
+                args="debounced(...args);"
+                props={{
+                    args: {
+                        description: { tr: "Değiştirilmeden fn fonksiyonuna iletilir.", en: "Forwarded to fn unchanged." },
+                        type: "any[]",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/libs/debouncedFunction/index.js

@@ -0,0 +1,121 @@
+import { generateRandom } from "../generateRandom";
+
+const ref = {};
+let cleanupIntervalId = null;
+const autoFunctionNameRef = new WeakMap();
+
+const getAutoFunctionName = (fn) => {
+    if (typeof fn !== "function") return generateRandom.text(16);
+    const current = autoFunctionNameRef.get(fn);
+    if (current) return current;
+    const next = generateRandom.text(16);
+    autoFunctionNameRef.set(fn, next);
+    return next;
+};
+
+const cleanupUnusedEntries = () => {
+    const now = Date.now();
+    for (const key in ref) {
+        if (!ref[key]?.lastUsed || now - ref[key].lastUsed > 60_000) {
+            if (ref[key]?.timeout) clearTimeout(ref[key].timeout);
+            delete ref[key];
+        }
+    }
+};
+
+if (typeof window !== "undefined" && !cleanupIntervalId) {
+    cleanupIntervalId = setInterval(cleanupUnusedEntries, 300_000);
+}
+
+export const debouncedFunction = (
+    fn,
+    {
+        delay = 500,
+        isThrottle = false,
+        getFirst = false,
+        functionName,
+        onStart,
+        onEnd,
+    } = {},
+) => {
+    if (!delay || delay < 100) return fn;
+    const scopedFunctionName = functionName || getAutoFunctionName(fn);
+    const shouldRunFirst = !isThrottle && getFirst;
+
+    const entry =
+        ref[scopedFunctionName] ||
+        (ref[scopedFunctionName] = {
+            timeout: null,
+            lastUsed: 0,
+            lastArgs: null,
+            calledDuringWait: false,
+            isWaiting: false,
+        });
+
+    if (!isThrottle) {
+        return (...args) => {
+            entry.lastUsed = Date.now();
+
+            const isFirstCallInWindow = entry.timeout == null;
+
+            if (isFirstCallInWindow) {
+                onStart?.(...args);
+            }
+
+            if (shouldRunFirst && isFirstCallInWindow) {
+                fn(...args);
+                entry.calledDuringWait = false;
+            } else if (entry.timeout != null) {
+                entry.calledDuringWait = true;
+            }
+
+            entry.lastArgs = args;
+
+            if (entry.timeout) clearTimeout(entry.timeout);
+
+            entry.timeout = setTimeout(() => {
+                if (!shouldRunFirst || entry.calledDuringWait) {
+                    fn(...entry.lastArgs);
+                }
+
+                entry.timeout = null;
+                entry.lastArgs = null;
+                entry.calledDuringWait = false;
+
+                onEnd?.();
+            }, delay);
+        };
+    }
+
+    return (...args) => {
+        entry.lastUsed = Date.now();
+        entry.lastArgs = args;
+
+        if (!entry.isWaiting) {
+            entry.isWaiting = true;
+
+            onStart?.(...args);
+
+            entry.calledDuringWait = true;
+
+            entry.timeout = setTimeout(() => {
+                entry.isWaiting = false;
+
+                if (entry.calledDuringWait) {
+                    fn(...entry.lastArgs);
+                }
+
+                if (entry.timeout) clearTimeout(entry.timeout);
+                entry.timeout = null;
+                entry.lastArgs = null;
+                entry.calledDuringWait = false;
+
+                onEnd?.();
+            }, delay);
+
+            return;
+        }
+
+        entry.calledDuringWait = true;
+    };
+};