@bariskuran/base 0.0.0-stage → 0.0.1

package/src/libs/Layout/_dS_headerAmedist.jsx

@@ -0,0 +1,139 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="<Layout.headerAmedist>"
+        releasedOn="1.0.0"
+        description={{
+            tr: "Logo, kontrollü search input, dil değiştirici ve menu toggle alanı içeren sticky Amedist header varyantıdır. Menü, search ve görünürlük state'i controller registry üzerinden paylaşılır.",
+            en: "Sticky Amedist header variant with logo, controlled search input, language switcher, and menu toggle areas. Menu, search, and visibility state are shared through the controller registry.",
+        }}
+    >
+        <Ds.block
+            title={{ tr: "Temel kullanım", en: "Basic usage" }}
+            code={`import { Layout } from "${SYS.basePath}";
+
+<Layout.headerAmedist
+    controllerId="main"
+    logo={{
+        tr: { extended: trLogo, condensed: trLogoSmall },
+        en: { extended: enLogo, condensed: enLogoSmall },
+    }}
+/>`}
+        />
+        <Ds.block
+            title={{ tr: "Controller çıktısı", en: "Controller output" }}
+            code={`const {
+    openMenu,
+    closeMenu,
+    toggleMenu,
+    menuStatus, // "opening" | "open" | "closing" | "closed"
+    searchValue,
+    setSearchValue,
+    clearSearchValue,
+    headerStatus, // "extended" | "condensed" | "hidden"
+    hideHeader,
+    showHeader,
+    extendedHeight,
+    condensedHeight,
+} = useLayout("headerAmedist", { controllerId: "main" });`}
+        />
+        <Ds.api
+            args="<Layout.headerAmedist logo />"
+            props={{
+                logo: {
+                    description: {
+                        tr: "ReactNode, tek asset URL'i veya language/status kırılımlı logo objesi.",
+                        en: "ReactNode, a single asset URL, or a logo object keyed by language and status.",
+                    },
+                    type: "ReactNode | string | object",
+                    required: true,
+                },
+                controllerId: {
+                    description: {
+                        tr: "Bu header controller instance'ının benzersiz kimliği.",
+                        en: "Unique identity of this header controller instance.",
+                    },
+                    type: "string",
+                    defaultValue: "default",
+                },
+                extendedHeight: {
+                    description: {
+                        tr: "Extended header yüksekliği.",
+                        en: "Extended header height.",
+                    },
+                    type: "number",
+                    defaultValue: "100",
+                },
+                condensedHeight: {
+                    description: {
+                        tr: "Condensed header yüksekliği.",
+                        en: "Condensed header height.",
+                    },
+                    type: "number",
+                    defaultValue: "50",
+                },
+                openIconProps: {
+                    description: {
+                        tr: "Menu açma ikonuna iletilen Icon prop objesi.",
+                        en: "Icon prop object forwarded to the menu-open icon.",
+                    },
+                    type: "object",
+                },
+                closeIconProps: {
+                    description: {
+                        tr: "Menu kapatma ikonuna iletilen Icon prop objesi.",
+                        en: "Icon prop object forwarded to the menu-close icon.",
+                    },
+                    type: "object",
+                },
+                headerColor: {
+                    description: {
+                        tr: "Extended header'ın varsayılan foreground rengi.",
+                        en: "Default foreground color of the extended header.",
+                    },
+                    type: "string",
+                    defaultValue: "foreground",
+                },
+                headerBackgroundColor: {
+                    description: { tr: "Header arka plan rengi.", en: "Header background color." },
+                    type: "string",
+                    defaultValue: "background",
+                },
+                headerBackgroundAlpha: {
+                    description: {
+                        tr: "Extended header'ın varsayılan arka plan alpha değeri.",
+                        en: "Default background alpha of the extended header.",
+                    },
+                    type: "number",
+                    defaultValue: "70",
+                },
+                hideHeader: {
+                    description: {
+                        tr: "Controller hideHeader/showHeader komutlarıyla birleşen controlled gizleme sinyali.",
+                        en: "Controlled hide signal combined with controller hideHeader/showHeader commands.",
+                    },
+                    type: "boolean",
+                    defaultValue: "false",
+                },
+                searchPlaceholder: {
+                    description: {
+                        tr: "Varsayılan searchInputPlaceholder metnini ezer.",
+                        en: "Overrides the default searchInputPlaceholder text.",
+                    },
+                    type: "string",
+                },
+                onLogoClick: {
+                    description: {
+                        tr: "Varsayılan ana sayfa navigasyonunu ezer; menu yine kapatılır.",
+                        en: "Overrides default home navigation; the menu is still closed.",
+                    },
+                    type: "function",
+                },
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/Layout/_dS_mainAmedist.jsx

@@ -0,0 +1,87 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="<Layout.mainAmedist>"
+        releasedOn="1.0.0"
+        description={{
+            tr: "Amedist sayfa kabuğu; header, footer ve menuContent slotlarını yerleştirir, menü lifecycle'ına göre ana içeriğin görünürlüğünü yönetir. Menü içeriğinin veri modelini veya iç tasarımını üretmez.",
+            en: "The Amedist page shell places header, footer, and menuContent slots and controls main-content visibility through the menu lifecycle. It does not own the menu content's data model or internal design.",
+        }}
+    >
+        <Ds.block
+            title={{ tr: "Temel kullanım", en: "Basic usage" }}
+            code={`import { Layout, Outlet } from "${SYS.basePath}";
+
+<Layout.mainAmedist
+    controllerId="main"
+    header={<Layout.headerAmedist controllerId="main" logo={logo} />}
+    footer={
+        <Layout.footerAmedist
+            controllerId="main"
+            logo={<Logo />}
+            links={<Links />}
+            credit={<Credit />}
+        />
+    }
+    menuContent={<MenuContent selectedLink={selectedLink} />}
+>
+    <Outlet />
+</Layout.mainAmedist>`}
+        />
+        <Ds.block
+            title={{ tr: "Controller kimliği", en: "Controller identity" }}
+            description={{
+                tr: "controllerId verilmezse default kullanılır. Aynı varyant ve controllerId ile birden fazla UI mount edilirse ilgili UI'ların tamamı görünür bir warning çıktısı verir. Toplu tetikleme için duplicate ID kullanılmamalıdır.",
+                en: "controllerId defaults to default. Mounting multiple UIs with the same variant and controllerId makes every affected UI render a visible warning. Duplicate IDs must not be used as a broadcast mechanism.",
+            }}
+        />
+        <Ds.api
+            args="<Layout.mainAmedist children />"
+            props={{
+                children: {
+                    description: {
+                        tr: "Menü kapalı veya kapanıyorken gösterilen ana içerik.",
+                        en: "Main content displayed while the menu is closed or closing.",
+                    },
+                    type: "ReactNode",
+                    required: true,
+                },
+                header: {
+                    description: { tr: "Header slotu.", en: "Header slot." },
+                    type: "ReactNode",
+                },
+                footer: {
+                    description: { tr: "Footer slotu.", en: "Footer slot." },
+                    type: "ReactNode",
+                },
+                menuContent: {
+                    description: {
+                        tr: "Opening, open ve closing durumlarında menu alanında gösterilen proje içeriği.",
+                        en: "Project-owned content shown in the menu area during opening, open, and closing states.",
+                    },
+                    type: "ReactNode",
+                },
+                controllerId: {
+                    description: {
+                        tr: "Bu main controller instance'ının benzersiz kimliği.",
+                        en: "Unique identity of this main controller instance.",
+                    },
+                    type: "string",
+                    defaultValue: "default",
+                },
+                visible: {
+                    description: {
+                        tr: "Layout ortak Visibility preserve kontrolü.",
+                        en: "Shared Layout Visibility preserve control.",
+                    },
+                    type: "boolean",
+                    defaultValue: "true",
+                },
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/Layout/_dS_useLayout.jsx

@@ -0,0 +1,55 @@
+import Ds from "../DesignSystem";
+import { SYS } from "../../constants/SYS";
+
+const X = () => (
+    <Ds.page
+        title="useLayout"
+        releasedOn="1.0.0"
+        description={{
+            tr: "useLayout, Layout varyantlarının controller çıktılarına erişir. Dönen state ve aksiyonlar varyanta göre değiştiği için bu sayfa yalnızca controller seçme biçimini açıklar. Kullanılabilir alanlar ve davranışlar için hedef Layout varyantının Design System sayfasına bakılmalıdır.",
+            en: "useLayout accesses controller outputs exposed by Layout variants. Since returned state and actions vary by variant, this page only documents controller selection. See the target Layout variant's Design System page for its available fields and behavior.",
+        }}
+    >
+        <Ds.block
+            title={{ tr: "Tek varyant", en: "Single variant" }}
+            description={{
+                tr: "String kullanım default controllerId değerini hedefler. Aynı varyantın isimlendirilmiş bir instance'ı için controllerId ayrıca verilebilir.",
+                en: "The string form targets the default controllerId. Provide controllerId when targeting a named instance of the same variant.",
+            }}
+            code={`import { useLayout } from "${SYS.basePath}";
+
+const header = useLayout("headerAmedist");
+
+const mainHeader = useLayout("headerAmedist", {
+    controllerId: "main",
+});`}
+        />
+        <Ds.block
+            title={{ tr: "Çoklu varyant", en: "Multiple variants" }}
+            description={{
+                tr: "Birden fazla controller array ile istenir. Sonuçlar selector'larla aynı sırada array olarak döner; farklı varyantların aynı isimli alanları birleştirilmez.",
+                en: "Request multiple controllers with an array. Results are returned as an array in selector order; same-named fields from different variants are not merged.",
+            }}
+            code={`const [header, footer, main] = useLayout([
+    { name: "headerAmedist", controllerId: "main" },
+    { name: "footerAmedist", controllerId: "main" },
+    { name: "mainAmedist", controllerId: "main" },
+]);
+
+// Each string uses controllerId: "default"
+const [defaultHeader, defaultFooter] = useLayout([
+    "headerAmedist",
+    "footerAmedist",
+]);`}
+        />
+        <Ds.block
+            title={{ tr: "Varyant API'ları", en: "Variant APIs" }}
+            description={{
+                tr: "useLayout dönüşleri ortak bir sözleşmeye zorlanmaz. Menu status, search aksiyonları, header status veya başka çıktılar yalnızca bunları sağlayan varyantın kendi sayfasında belgelenir.",
+                en: "useLayout results are not forced into one shared contract. Menu status, search actions, header status, and other outputs are documented only on the page of the variant that provides them.",
+            }}
+        />
+    </Ds.page>
+);
+
+export default X;

package/src/libs/Layout/controllerRegistry.js

@@ -0,0 +1,121 @@
+import { useEffect, useRef, useSyncExternalStore } from "react";
+
+const DEFAULT_CONTROLLER_ID = "default";
+const factories = new Map();
+const entries = new Map();
+const listeners = new Set();
+let version = 0;
+
+const notify = () => {
+    version += 1;
+    listeners.forEach((listener) => listener());
+};
+
+const subscribe = (listener) => {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+};
+
+const getVersion = () => version;
+const getControllerKey = (name, controllerId) => `${name}:${controllerId}`;
+
+const createBasicController = () => {
+    const state = {};
+    return {
+        getState: () => state,
+        getPublicState: () => ({}),
+    };
+};
+
+export const registerLayoutControllerFactory = (name, factory) => {
+    factories.set(name, factory);
+};
+
+export const normalizeControllerId = (controllerId) =>
+    controllerId == null || controllerId === "" ? DEFAULT_CONTROLLER_ID : String(controllerId);
+
+export const getLayoutControllerEntry = (name, controllerId = DEFAULT_CONTROLLER_ID) => {
+    const normalizedId = normalizeControllerId(controllerId);
+    const key = getControllerKey(name, normalizedId);
+
+    if (!entries.has(key)) {
+        const factory = factories.get(name) || createBasicController;
+        entries.set(key, {
+            key,
+            name,
+            controllerId: normalizedId,
+            controller: factory({ notify }),
+            owners: new Set(),
+        });
+    }
+
+    return entries.get(key);
+};
+
+const getPublicController = (name, controllerId) => {
+    const entry = getLayoutControllerEntry(name, controllerId);
+    return {
+        ...entry.controller.getPublicState(),
+        controllerName: entry.name,
+        controllerId: entry.controllerId,
+        hasDuplicateController: entry.owners.size > 1,
+    };
+};
+
+const normalizeSelector = (selector, options = {}) => {
+    if (typeof selector === "string") {
+        return {
+            name: selector,
+            controllerId: normalizeControllerId(options.controllerId),
+        };
+    }
+
+    if (selector && typeof selector === "object" && !Array.isArray(selector)) {
+        return {
+            name: selector.name,
+            controllerId: normalizeControllerId(selector.controllerId),
+        };
+    }
+
+    return { name: "", controllerId: DEFAULT_CONTROLLER_ID };
+};
+
+export const useLayout = (selector, options = {}) => {
+    useSyncExternalStore(subscribe, getVersion, getVersion);
+
+    if (Array.isArray(selector)) {
+        return selector.map((item) => {
+            const normalized = normalizeSelector(item);
+            return getPublicController(normalized.name, normalized.controllerId);
+        });
+    }
+
+    const normalized = normalizeSelector(selector, options);
+    return getPublicController(normalized.name, normalized.controllerId);
+};
+
+export const useLayoutControllerOwner = (name, controllerId) => {
+    const ownerRef = useRef(null);
+    if (!ownerRef.current) ownerRef.current = Symbol(`${name}:${controllerId}`);
+
+    const entry = getLayoutControllerEntry(name, controllerId);
+    useSyncExternalStore(subscribe, getVersion, getVersion);
+
+    useEffect(() => {
+        entry.owners.add(ownerRef.current);
+        notify();
+
+        return () => {
+            entry.owners.delete(ownerRef.current);
+            notify();
+        };
+    }, [entry]);
+
+    return {
+        hasDuplicateController: entry.owners.size > 1,
+        controllerId: entry.controllerId,
+    };
+};
+
+export const getLayoutController = (name, controllerId) =>
+    getLayoutControllerEntry(name, controllerId).controller;

package/src/libs/Layout/controllerRegistry.test.jsx

@@ -0,0 +1,99 @@
+import { act, render, renderHook, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+    registerLayoutControllerFactory,
+    useLayout,
+    useLayoutControllerOwner,
+} from "./controllerRegistry";
+import {
+    createBasicLayoutController,
+    createFooterAmedistController,
+    createHeaderAmedistController,
+} from "./controllers";
+
+describe("Layout controller registry", () => {
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it("supports single and ordered multi-controller selectors", () => {
+        registerLayoutControllerFactory("testMain", createBasicLayoutController);
+        registerLayoutControllerFactory("testFooter", createBasicLayoutController);
+
+        const { result: single } = renderHook(() =>
+            useLayout("testMain", { controllerId: "main" }),
+        );
+        expect(single.current.controllerId).toBe("main");
+
+        const { result: multiple } = renderHook(() =>
+            useLayout([
+                { name: "testMain", controllerId: "main" },
+                { name: "testFooter", controllerId: "secondary" },
+            ]),
+        );
+        expect(multiple.current.map((controller) => controller.controllerId)).toEqual([
+            "main",
+            "secondary",
+        ]);
+    });
+
+    it("marks every mounted owner when name and controllerId are duplicated", async () => {
+        const Probe = () => {
+            const { hasDuplicateController } = useLayoutControllerOwner("duplicateTest", "same");
+            return <div>{hasDuplicateController ? "duplicate" : "ok"}</div>;
+        };
+
+        render(
+            <>
+                <Probe />
+                <Probe />
+            </>,
+        );
+
+        expect(await screen.findAllByText("duplicate")).toHaveLength(2);
+    });
+
+    it("combines menu, search, and hidden header sources in headerAmedist", () => {
+        vi.useFakeTimers();
+        let notifications = 0;
+        const controller = createHeaderAmedistController({
+            notify: () => {
+                notifications += 1;
+            },
+        });
+
+        controller.setSearchValue("sur");
+        expect(controller.getPublicState().searchValue).toBe("sur");
+        expect(controller.getPublicState().menuStatus).toBe("opening");
+
+        act(() => vi.advanceTimersByTime(500));
+        expect(controller.getPublicState().menuStatus).toBe("open");
+
+        controller.hideHeader();
+        controller.hideHeaderFromProp(true);
+        controller.showHeader();
+        expect(controller.getPublicState().headerStatus).toBe("hidden");
+
+        controller.hideHeaderFromProp(false);
+        expect(controller.getPublicState().headerStatus).toBe("extended");
+        expect(notifications).toBeGreaterThan(0);
+    });
+
+    it("combines hidden footer sources without clearing other consumers", () => {
+        let notifications = 0;
+        const controller = createFooterAmedistController({
+            notify: () => {
+                notifications += 1;
+            },
+        });
+
+        controller.hideFooter("storyteller");
+        controller.hideFooter("modal");
+        controller.showFooter("storyteller");
+        expect(controller.getPublicState().visible).toBe(false);
+
+        controller.showFooter("modal");
+        expect(controller.getPublicState().visible).toBe(true);
+        expect(notifications).toBe(4);
+    });
+});

package/src/libs/Layout/controllers.js

@@ -0,0 +1,169 @@
+const MENU_TRANSITION_MS = 500;
+const VALID_HEADER_STATUS = ["extended", "condensed"];
+
+const getLastMapValue = (map) => {
+    const values = Array.from(map.values());
+    return values.length ? values[values.length - 1] : null;
+};
+
+export const createHeaderAmedistController = ({ notify }) => {
+    const hiddenSources = new Set();
+    const appearanceSources = new Map();
+    let menuTimer = null;
+    const state = {
+        menuStatus: "closed",
+        searchValue: "",
+        visibleHeaderStatus: "extended",
+        extendedHeight: 100,
+        condensedHeight: 50,
+    };
+
+    const update = (updater) => {
+        updater(state);
+        notify();
+    };
+
+    const clearMenuTimer = () => {
+        if (menuTimer != null) clearTimeout(menuTimer);
+        menuTimer = null;
+    };
+
+    const finishMenuTransition = (status) => {
+        clearMenuTimer();
+        menuTimer = setTimeout(() => {
+            update((draft) => {
+                draft.menuStatus = status;
+            });
+            menuTimer = null;
+        }, MENU_TRANSITION_MS);
+    };
+
+    const openMenu = () => {
+        if (state.menuStatus === "open" || state.menuStatus === "opening") return;
+        clearMenuTimer();
+        update((draft) => {
+            draft.menuStatus = "opening";
+        });
+        finishMenuTransition("open");
+    };
+
+    const closeMenu = () => {
+        if (state.menuStatus === "closed" || state.menuStatus === "closing") return;
+        clearMenuTimer();
+        update((draft) => {
+            draft.menuStatus = "closing";
+            draft.searchValue = "";
+        });
+        finishMenuTransition("closed");
+    };
+
+    const hideHeader = (source = "manual") => {
+        const size = hiddenSources.size;
+        hiddenSources.add(source);
+        if (hiddenSources.size !== size) notify();
+    };
+
+    const showHeader = (source = "manual") => {
+        if (hiddenSources.delete(source)) notify();
+    };
+
+    const publicActions = {
+        openMenu,
+        closeMenu,
+        toggleMenu: () =>
+            state.menuStatus === "open" || state.menuStatus === "opening"
+                ? closeMenu()
+                : openMenu(),
+        setSearchValue: (value) => {
+            update((draft) => {
+                draft.searchValue = value == null ? "" : String(value);
+            });
+            if (value) openMenu();
+        },
+        clearSearchValue: () =>
+            update((draft) => {
+                draft.searchValue = "";
+            }),
+        hideHeader,
+        showHeader,
+    };
+
+    const internalActions = {
+        setHeaderStatus: (status) => {
+            if (!VALID_HEADER_STATUS.includes(status) || state.visibleHeaderStatus === status)
+                return;
+            update((draft) => {
+                draft.visibleHeaderStatus = status;
+            });
+        },
+        setHeaderHeights: ({ extendedHeight, condensedHeight }) => {
+            const nextExtended = Number(extendedHeight) || 100;
+            const nextCondensed = Number(condensedHeight) || 50;
+            if (state.extendedHeight === nextExtended && state.condensedHeight === nextCondensed)
+                return;
+            update((draft) => {
+                draft.extendedHeight = nextExtended;
+                draft.condensedHeight = nextCondensed;
+            });
+        },
+        setHeaderAppearance: (source, appearance) => {
+            appearanceSources.delete(source);
+            appearanceSources.set(source, appearance || {});
+            notify();
+        },
+        clearHeaderAppearance: (source) => {
+            if (appearanceSources.delete(source)) notify();
+        },
+        hideHeaderFromProp: (hidden) => (hidden ? hideHeader("prop") : showHeader("prop")),
+    };
+
+    return {
+        getState: () => ({
+            ...state,
+            headerStatus: hiddenSources.size ? "hidden" : state.visibleHeaderStatus,
+            headerAppearance: getLastMapValue(appearanceSources),
+        }),
+        getPublicState: () => ({
+            menuStatus: state.menuStatus,
+            searchValue: state.searchValue,
+            headerStatus: hiddenSources.size ? "hidden" : state.visibleHeaderStatus,
+            extendedHeight: state.extendedHeight,
+            condensedHeight: state.condensedHeight,
+            ...publicActions,
+        }),
+        ...publicActions,
+        ...internalActions,
+    };
+};
+
+export const createBasicLayoutController = () => ({
+    getState: () => ({}),
+    getPublicState: () => ({}),
+});
+
+export const createFooterAmedistController = ({ notify }) => {
+    const hiddenSources = new Set();
+
+    const hideFooter = (source = "manual") => {
+        const size = hiddenSources.size;
+        hiddenSources.add(source);
+        if (hiddenSources.size !== size) notify();
+    };
+
+    const showFooter = (source = "manual") => {
+        if (hiddenSources.delete(source)) notify();
+    };
+
+    const getVisible = () => hiddenSources.size === 0;
+
+    return {
+        getState: () => ({ visible: getVisible() }),
+        getPublicState: () => ({
+            visible: getVisible(),
+            hideFooter,
+            showFooter,
+        }),
+        hideFooter,
+        showFooter,
+    };
+};