@bariskuran/base 0.0.0-stage → 0.0.2

package/src/libs/DesignSystem/Layout/_styled.js

@@ -0,0 +1,40 @@
+import styled, { css } from "styled-components";
+
+export const S = {
+    container: styled.div`
+        width: 100%;
+        min-width: 0;
+        display: flex;
+        align-items: flex-start;
+
+        ${({ theme }) => css`
+            background-color: ${theme.background};
+            color: ${theme.foreground};
+        `}
+    `,
+    navigation: styled.div`
+        box-sizing: border-box;
+        position: sticky;
+        top: 0;
+        align-self: flex-start;
+        flex: 0 0 300rem;
+        min-height: 100vh;
+        max-height: 100vh;
+        min-height: 100dvh;
+        max-height: 100dvh;
+    `,
+    logoArea: styled.div`
+        position: sticky;
+        top: 25rem;
+        left: 0;
+        width: 100%;
+        display: flex;
+        justify-content: flex-start;
+        align-items: flex-start;
+        margin-top: 25rem;
+    `,
+    logoArea2: styled.div`
+        transform: rotate(-90deg);
+        transform-origin: center bottom;
+    `,
+};

package/src/libs/DesignSystem/Layout/index.jsx

@@ -0,0 +1,107 @@
+import { Outlet } from "react-router-dom";
+import { S } from "./_styled";
+import { baseStore } from "../../baseStore";
+import { Button } from "../../Button";
+import useVars from "./useVars";
+import { sortBy } from "../../sortBy";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from "react";
+import { useLocation } from "react-router-dom";
+import { ScrollBar } from "../../ScrollBar";
+import { Flex } from "../../Flex";
+import { useRevealNavItem } from "../../useRevealNavItem";
+
+const resetDocumentScroll = () => {
+    if (typeof window === "undefined") return;
+    window.scrollTo(0, 0);
+    document.documentElement.scrollTop = 0;
+    document.body.scrollTop = 0;
+};
+
+const fallbackFormatNavLabel = (name) => String(name ?? "");
+
+const Layout = ({ getSitemap: getSitemapProp = () => [], formatNavLabel = fallbackFormatNavLabel }) => {
+    const vars = useVars();
+    const { pathname } = useLocation();
+    const navScrollRef = useRef(null);
+    const showInternalDs = baseStore.useGlobal((s) => !!s._adminSettings?.showInternalDs);
+    const sorted = useMemo(() => {
+        const list = getSitemapProp() || [];
+        const pinnedCount = 2;
+        const pinned = list.slice(0, pinnedCount);
+        const rest = list.slice(pinnedCount).sort((a, b) => sortBy.asc(a[0], b[0]));
+        return [...pinned, ...rest];
+    }, [showInternalDs, getSitemapProp]);
+
+    useLayoutEffect(() => {
+        if (typeof history !== "undefined" && "scrollRestoration" in history) {
+            history.scrollRestoration = "manual";
+        }
+    }, []);
+
+    const resetContentScroll = useCallback(() => {
+        resetDocumentScroll();
+    }, []);
+
+    useLayoutEffect(() => {
+        resetContentScroll();
+    }, [pathname, resetContentScroll]);
+
+    useEffect(() => {
+        resetContentScroll();
+    }, [pathname, resetContentScroll]);
+
+    const [isActive, activeNavItemRef] = useRevealNavItem({
+        links: sorted,
+        basePath: "/design-system",
+        getPathFromLink: (link) => link[1],
+        scrollRootRef: navScrollRef,
+    });
+
+    /* RETURN */
+    return (
+        <S.container $vars={vars} aria-label="Design System">
+            <ScrollBar.primary body maxLength={40} fillMode />
+            <S.navigation aria-label="Navigation">
+                <Flex.column ref={navScrollRef} height="100vh" flex="0 0 300rem" paddingBottom={75}>
+                    <ScrollBar disableX trackMargin={0} edgeMargin={-4} />
+                    <S.logoArea>
+                        <S.logoArea2>
+                            <Button.plain
+                                to="/design-system"
+                                bgColor="transparent"
+                                hoverBgColor="transparent"
+                                activeBgColor="transparent"
+                                icon={{
+                                    disablePulseEffect: true,
+                                    disableScaleEffect: true,
+                                    icon: "baseLogo",
+                                    color: "primary",
+                                    width: 125,
+                                    flat: true,
+                                }}
+                            />
+                        </S.logoArea2>
+                    </S.logoArea>
+                    {sorted.map((entry, i) => {
+                        const [name, path] = entry;
+                        return (
+                            <Button.squareOnRight
+                                key={path ?? `nav-${i}`}
+                                ref={isActive(entry) ? activeNavItemRef : undefined}
+                                to={path ? `/design-system/${path}` : "/design-system"}
+                                label={formatNavLabel(name)}
+                                bgColor="transparent"
+                                color="foreground"
+                                fullWidth="right"
+                            />
+                        );
+                    })}
+                </Flex.column>
+            </S.navigation>
+            <Flex.column full flex="1 1 0%" gap={10} padding="30rem" minWidth={0}>
+                <Outlet />
+            </Flex.column>
+        </S.container>
+    );
+};
+export default Layout;

package/src/libs/DesignSystem/Layout/tools/pageTitle.js

@@ -0,0 +1,4 @@
+export const DEFAULT_PAGE_TITLE = "Design System";
+
+export const resolvePageTitleFromMatches = (matches, fallback = DEFAULT_PAGE_TITLE) =>
+    [...matches].reverse().find((m) => m.handle?.pageTitle)?.handle?.pageTitle || fallback;

package/src/libs/DesignSystem/Layout/useVars.js

@@ -0,0 +1,15 @@
+import { useMatches } from "react-router-dom";
+import { useEffect } from "react";
+import { DEFAULT_PAGE_TITLE, resolvePageTitleFromMatches } from "./tools/pageTitle";
+
+const useVars = () => {
+    const matches = useMatches();
+    const pageTitle = resolvePageTitleFromMatches(matches);
+    useEffect(() => {
+        document.title = DEFAULT_PAGE_TITLE + " | " + pageTitle;
+    }, [pageTitle]);
+
+    /*  Return */
+    return {};
+};
+export default useVars;

package/src/libs/DesignSystem/OutputArea/index.jsx

@@ -0,0 +1,150 @@
+import { Typo } from "../../Typo";
+import { Button } from "../../Button";
+import styled from "styled-components";
+import { Flex } from "../../Flex";
+import { useMemo } from "react";
+import { copyToClipboard } from "../../copyToClipboard";
+import { coerceToCodeText } from "../formatJsonForDisplay";
+
+const ButtonArea = styled.div`
+    position: absolute;
+    right: 10rem;
+    top: 10rem;
+    z-index: 2;
+`;
+
+const OutputCodeBlock = styled.div`
+    min-width: 0;
+    max-width: 100%;
+    width: 100%;
+    overflow: hidden;
+    box-sizing: border-box;
+
+    pre {
+        margin: 0;
+        max-width: 100%;
+        white-space: pre-wrap !important;
+        overflow-wrap: anywhere;
+        word-break: break-word;
+    }
+`;
+
+const OutputArea = ({
+    outputs,
+    path,
+    onClose,
+    set,
+    directValue,
+    label = "Output",
+    disableFnString = false,
+}) => {
+    const handleClose = () => {
+        if (onClose) {
+            onClose(path);
+            return;
+        }
+
+        set?.((s) => {
+            s.outputs[path] = null;
+        });
+    };
+
+    const pathValue = outputs?.[path];
+    const gateDirectValue = directValue !== undefined && path != null;
+    const isOpen = gateDirectValue ? pathValue != null : true;
+
+    const [outputValue, stringFn] = useMemo(() => {
+        if (directValue !== undefined) {
+            if (!isOpen) return [null, ""];
+
+            const value = directValue;
+            if (value == null) return [null, ""];
+
+            if (typeof value === "string") return [coerceToCodeText(value), ""];
+            return [coerceToCodeText(value), ""];
+        }
+
+        const value = pathValue;
+        if (value == null) return [null, ""];
+
+        if (
+            typeof value === "object" &&
+            value !== null &&
+            !Array.isArray(value) &&
+            typeof value.fn === "string" &&
+            Object.prototype.hasOwnProperty.call(value, "output")
+        ) {
+            const rawOut = value.output;
+            const out = coerceToCodeText(rawOut);
+            const f = typeof value.fn === "string" ? value.fn : "";
+            return [out, f];
+        }
+
+        if (typeof value === "string") return [coerceToCodeText(value), ""];
+        return [coerceToCodeText(value), ""];
+    }, [directValue, pathValue, isOpen]);
+
+    if ((outputValue == null || outputValue === "") && (!stringFn || stringFn === "")) return null;
+    const codeBlockProps = {
+        codeFormat: true,
+        codeFormatJsxProps: false,
+        full: true,
+        disableMaxWidthLock: true,
+        whiteSpace: "pre-wrap",
+        width: "100%",
+        margin: 0,
+        padding: 0,
+    };
+
+    return (
+        <Flex.column
+            full
+            minWidth={0}
+            bgColor="foreground"
+            color="background"
+            padding={20}
+            userSelect="none"
+        >
+            <ButtonArea>
+                {stringFn ? (
+                    <Button
+                        icon={{ icon: "copy", width: 14 }}
+                        onClick={() => {
+                            copyToClipboard(stringFn);
+                        }}
+                    />
+                ) : null}
+                <Button icon={{ icon: "close", width: 12 }} onClick={handleClose} />
+            </ButtonArea>
+            {stringFn && !disableFnString ? (
+                <Flex.column full minWidth={0} gap={6}>
+                    <Typo.bold balance underline>
+                        fn
+                    </Typo.bold>
+                    <OutputCodeBlock>
+                        <Typo.code content={stringFn} {...codeBlockProps} codeFormatCalls />
+                    </OutputCodeBlock>
+                </Flex.column>
+            ) : null}
+            <Flex.column
+                full
+                minWidth={0}
+                gap={6}
+                marginTop={stringFn && !disableFnString ? 12 : 0}
+            >
+                <Typo.bold balance underline>
+                    {label}
+                </Typo.bold>
+                <OutputCodeBlock>
+                    <Typo.code
+                        content={outputValue ?? ""}
+                        {...codeBlockProps}
+                        codeFormatCalls={false}
+                    />
+                </OutputCodeBlock>
+            </Flex.column>
+        </Flex.column>
+    );
+};
+
+export default OutputArea;

package/src/libs/DesignSystem/Page/index.jsx

@@ -0,0 +1,56 @@
+import { Typo } from "../../Typo";
+import { Flex } from "../../Flex";
+import { isJsxDescription } from "../isJsxDescription";
+import { templateLiteralTo } from "../../templateLiteralTo";
+import { t } from "../../getText";
+
+const Page = ({ children, title, releasedOn, description }) => {
+    const displayTitle = isJsxDescription(title) ? title : t(title);
+    const displayDescription = isJsxDescription(description) ? description : t(description);
+
+    return (
+        <Flex.column full>
+            <Flex.column full>
+                <Flex full>
+                    <Flex.column
+                        minWidth={250}
+                        alignItems="stretch"
+                        justifyContent="stretch"
+                        borderRight="1px solid greys.shade40"
+                    >
+                        <Flex.column flex="1 1 auto" yAlign="center" paddingRight={30}>
+                            <Typo.h1 alignSelf="center" color="greys.shade40" size={100}>
+                                {displayTitle}
+                            </Typo.h1>
+                            {releasedOn && (
+                                <Typo.span size={12} balance>
+                                    (Relased On: {releasedOn})
+                                </Typo.span>
+                            )}
+                        </Flex.column>
+                        <Flex height={1} flex="0 0 1px" full>
+                            <Flex flex="0 0 175rem" width={175} height={1} />
+                            <Flex flex="1 1 auto" height={1} bgColor="greys.shade40" />
+                        </Flex>
+                    </Flex.column>
+                    <Flex.column
+                        flex="1 1 auto"
+                        padding="0 15rem 0 30rem"
+                        minHeight={100}
+                        justify="center"
+                        margin="50rem 0"
+                    >
+                        {displayDescription &&
+                            (isJsxDescription(description) ? (
+                                <Typo as="div">{description}</Typo>
+                            ) : (
+                                <Typo as="div">{templateLiteralTo.p(displayDescription)}</Typo>
+                            ))}
+                    </Flex.column>
+                </Flex>
+            </Flex.column>
+            {children}
+        </Flex.column>
+    );
+};
+export default Page;

package/src/libs/DesignSystem/Routes.jsx

@@ -0,0 +1,27 @@
+import { Route, Routes } from "react-router-dom";
+import Layout from "./Layout";
+import { formatDsNavLabel, getSitemap } from ".";
+
+const DesignSystemRoutes = () => {
+    return (
+        <Routes>
+            <Route
+                element={<Layout getSitemap={getSitemap} formatNavLabel={formatDsNavLabel} />}
+            >
+                {getSitemap().map(([name, path, El, props]) => (
+                    <Route
+                        key={path || "index"}
+                        path={path}
+                        element={<El />}
+                        {...props}
+                        handle={{
+                            pageTitle: formatDsNavLabel(name),
+                        }}
+                    />
+                ))}
+            </Route>
+        </Routes>
+    );
+};
+
+export default DesignSystemRoutes;

package/src/libs/DesignSystem/VariantViewer/_styled.js

@@ -0,0 +1,22 @@
+import styled from "styled-components";
+
+const S = {
+    container: styled.div`
+        width: 100%;
+        display: flex;
+        gap: 10rem;
+        flex-wrap: wrap;
+        justify-content: flex-start;
+        align-items: flex-start;
+
+        & > div {
+            width: max-content;
+
+            & > div[data-slot="title"] {
+                margin-bottom: 10rem;
+                cursor: pointer;
+            }
+        }
+    `,
+};
+export default S;

package/src/libs/DesignSystem/VariantViewer/index.jsx

@@ -0,0 +1,20 @@
+import S from "./_styled";
+import { Icon } from "../../Icon";
+import { copyToClipboard } from "../../copyToClipboard";
+
+const VariantViewer = ({ variants }) => {
+    /* RETURN */
+    return (
+        <S.container>
+            {variants.map(([name, example]) => (
+                <div key={name} data-slot="variant">
+                    <div data-slot="title" onClick={() => copyToClipboard(name)}>
+                        <Icon icon="dotSmall" width={12} /> {name}
+                    </div>
+                    <div>{example}</div>
+                </div>
+            ))}
+        </S.container>
+    );
+};
+export default VariantViewer;

package/src/libs/DesignSystem/_dS.jsx

@@ -0,0 +1,60 @@
+import Ds from "./index";
+import { t } from "../getText";
+
+const X = () => (
+    <Ds.page
+        title={t({ tr: "Design System", en: "Design System" })}
+        releasedOn="1.0.0"
+        description={t({
+            tr: (
+                <>
+                    <b>Design System</b>, base içindeki komponentleri, hookları, yardımcı
+                    fonksiyonları ve proje kurulum kararlarını canlı örneklerle incelemek için
+                    kullanılan geliştirme dokümantasyonudur. Normal kullanımda uygulamanın üretim
+                    çıktısına dahil edilmez; böylece son kullanıcıya giden bundle gereksiz
+                    dokümantasyon kodu taşımaz.
+                </>
+            ),
+            en: (
+                <>
+                    <b>Design System</b> is the development documentation used to inspect base
+                    components, hooks, helpers, and setup decisions with live examples. It is not
+                    included in the production output by default, so the user-facing bundle does not
+                    carry unnecessary documentation code.
+                </>
+            ),
+        })}
+    >
+        <Ds.block
+            title={t({ tr: "Çalışma Modeli", en: "Runtime Model" })}
+            description={t({
+                tr: (
+                    <>
+                        Design System development ortamında otomatik çalışır. Production build
+                        içinde görünmesi istenirse proje tarafında build-time environment variable
+                        olarak <b>VITE_ENABLE_DESIGN_SYSTEM=true</b> verilmelidir. Mevcut projede
+                        bu değer <b>false</b> tutulur. Değişken <b>true</b> değilse Design System
+                        route'u üretim router'ına eklenmez.
+                    </>
+                ),
+                en: (
+                    <>
+                        Design System works automatically in development. If it must be available in
+                        a production build, set <b>VITE_ENABLE_DESIGN_SYSTEM=true</b> as a
+                        build-time environment variable in the project. This project keeps it as{" "}
+                        <b>false</b> by default. When this variable is missing or not <b>true</b>,
+                        the Design System route is not added to the production router.
+                    </>
+                ),
+            })}
+            code={`# .env
+VITE_ENABLE_DESIGN_SYSTEM=false
+
+# production build içinde Design System gerekli ise
+VITE_ENABLE_DESIGN_SYSTEM=true yarn build`}
+            lastBlock
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/DesignSystem/_dS_welcome.jsx

@@ -0,0 +1,48 @@
+import Ds from "./index";
+import { Button } from "../Button";
+// import { Typo } from "../Typo";
+import { t } from "../getText";
+
+const X = () => (
+    <Ds.page
+        title={t({ tr: "base Hakkında", en: "About base" })}
+        releasedOn="1.0.0"
+        description={t({
+            tr: (
+                <>
+                    <b>@bariskuran/base</b> bileşen ve yardımcı kütüphanelerinin canlı
+                    dokümantasyonu. Kurulum için{" "}
+                    <Button.string to="/design-system/how-to-setup" label="How To Setup" />{" "}
+                    sayfasına,
+                    <b>Design System</b> çalışma modeli için{" "}
+                    <Button.string to="/design-system/design-sistem" label="Design System" />{" "}
+                    sayfasına,
+                    <b>Base</b> ve <b>PROJECT_SETTINGS</b> detayları için{" "}
+                    <Button.string to="/design-system/base" label="Base" /> sayfasına gidin.
+                </>
+            ),
+            en: (
+                <>
+                    Live documentation for <b>@bariskuran/base</b> components and helpers. See{" "}
+                    <Button.string to="/design-system/how-to-setup" label="How To Setup" /> for
+                    installation,{" "}
+                    <Button.string to="/design-system/design-sistem" label="Design System" /> for
+                    runtime behavior, and the{" "}
+                    <Button.string to="/design-system/base" label="Base" /> page for{" "}
+                    <b>PROJECT_SETTINGS</b>.
+                </>
+            ),
+        })}
+    >
+        <Ds.block
+            title={t({ tr: "Navigasyon", en: "Navigation" })}
+            description={t({
+                tr: "Sol menüde Welcome ve How To Setup üstte; diğer sayfalar A–Z sıralıdır.",
+                en: "The left nav keeps Welcome and How To Setup at the top; other pages are A–Z.",
+            })}
+            lastBlock
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/DesignSystem/formatJsonForDisplay.js

@@ -0,0 +1,110 @@
+export const jsonDisplayReplacer = (_key, v) => {
+    if (v === undefined) return "undefined";
+    if (typeof v === "number" && Number.isNaN(v)) return "NaN";
+    if (typeof v === "function") return `[Function${v.name ? ` ${v.name}` : ""}]`;
+    return v;
+};
+
+const safeStringify = (value, space = 2) => {
+    const seen = new WeakSet();
+
+    return JSON.stringify(
+        value,
+        (key, v) => {
+            if (typeof v === "function") {
+                return `[Function${v.name ? ` ${v.name}` : ""}]`;
+            }
+
+            if (typeof v === "object" && v !== null) {
+                if (seen.has(v)) return "[Circular]";
+                seen.add(v);
+            }
+
+            return jsonDisplayReplacer(key, v);
+        },
+        space,
+    );
+};
+
+export const formatJsonForDisplay = (value) => {
+    if (typeof value === "string") return value;
+    if (value === undefined) return "undefined";
+    if (value === null) return "null";
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    if (typeof value === "function") return value.toString();
+
+    try {
+        const json = safeStringify(value);
+        return typeof json === "string" ? json : String(value);
+    } catch {
+        return String(value);
+    }
+};
+
+const TINT_SHADE_SCALE_COMMENT = "/* tint1...100 && shade1...100 */";
+
+const isTintShadeScaleObject = (value) => {
+    if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+    const keys = Object.keys(value);
+    if (keys.length === 0) return false;
+
+    const isScaleKey = (key) => /^tint\d+$/.test(key) || /^shade\d+$/.test(key);
+    if (!keys.some(isScaleKey)) return false;
+
+    return keys.every(isScaleKey);
+};
+
+const formatDisplayValue = (value, indent = 0, seen = new WeakSet()) => {
+    if (value === undefined) return "undefined";
+    if (value === null) return "null";
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    if (typeof value === "function") return `[Function${value.name ? ` ${value.name}` : ""}]`;
+    if (typeof value === "string") return JSON.stringify(value);
+
+    if (typeof value === "object") {
+        if (seen.has(value)) return '"[Circular]"';
+        seen.add(value);
+    }
+
+    if (isTintShadeScaleObject(value)) {
+        return `{ ${TINT_SHADE_SCALE_COMMENT} }`;
+    }
+
+    if (Array.isArray(value)) {
+        if (value.length === 0) return "[]";
+        const pad = " ".repeat(indent);
+        const inner = " ".repeat(indent + 2);
+        const lines = value.map((item) => `${inner}${formatDisplayValue(item, indent + 2, seen)}`);
+        return `[\n${lines.join(",\n")}\n${pad}]`;
+    }
+
+    const keys = Object.keys(value);
+    if (keys.length === 0) return "{}";
+
+    const pad = " ".repeat(indent);
+    const inner = " ".repeat(indent + 2);
+    const lines = keys.map((key) => {
+        const keyStr = JSON.stringify(key);
+        const formatted = formatDisplayValue(value[key], indent + 2, seen);
+        return `${inner}${keyStr}: ${formatted}`;
+    });
+
+    return `{\n${lines.join(",\n")}\n${pad}}`;
+};
+
+export const formatGlobalDataForDisplay = (value) => {
+    try {
+        return formatDisplayValue(value, 0);
+    } catch {
+        return formatJsonForDisplay(value);
+    }
+};
+
+export const coerceToCodeText = (value) => {
+    if (value == null || value === "") return null;
+    if (typeof value === "string") return value;
+    if (typeof value === "number" || typeof value === "boolean") return String(value);
+    if (typeof value === "function") return value.toString();
+
+    return formatJsonForDisplay(value);
+};