@bariskuran/base 0.0.0-stage → 0.0.1

package/src/design-system.js

@@ -0,0 +1,5 @@
+// Design System is deliberately a separate entry point. Re-exporting it from
+// the runtime entry makes Vite discover every documentation page and its lazy
+// imports even when the Design System route is disabled for production.
+export { default } from "./libs/DesignSystem";
+export { default as DS } from "./libs/DesignSystem";

package/src/helpers/NestedBaseUi/_dS.jsx

@@ -0,0 +1,70 @@
+import Ds from "libs/DesignSystem";
+import { SYS } from "../../constants/SYS";
+import { Typo } from "libs/Typo";
+import { Flex } from "libs/Flex";
+
+const X = () => {
+    return (
+        <Ds.page
+            title="NestedBaseUi"
+            releasedOn="1.0.0"
+            description={`NestedBaseUi is an internal UI-layer context provider used to prevent variant conflicts in nested UI components.
+
+When UI components are deeply nested (for example PopOver > ButtonGroup > ScrollFlex), each one may have its own default variant. Even if they do not technically override each other, combining all default variants creates visual noise. NestedBaseUi marks nested components so inner components can switch to plain behavior instead of applying another full variant style stack.
+
+In short: outer UI component keeps the main variant, inner UI components fall back to plain-like behavior to avoid design collisions.
+
+At this stage, this is mainly architectural documentation. Usage examples will be expanded when higher-level Table/layout integrations are finalized.`}
+        >
+            <Ds.block
+                title="Intent (architecture note)"
+                code={`import NestedBaseUi from "${SYS.basePath}/helpers/NestedBaseUi";
+
+                       // conceptual nesting example
+                       <PopOver>
+                       <ButtonGroup>
+                       <ScrollFlex>
+                       ...
+                       </ScrollFlex>
+                       </ButtonGroup>
+                       </PopOver>`}
+                example={
+                    <Flex.column gap={10}>
+                        <Typo.p>
+                            Context value carries the nesting flag so component creators can detect parent UI
+                            boundaries and avoid applying full default variants on inner layers.
+                        </Typo.p>
+                        <Typo.code>{`{
+  "__hasParentUiComponent": true,
+  "__typoPhrasingHost": true
+}`}</Typo.code>
+                    </Flex.column>
+                }
+            />
+
+            <Ds.api
+                args={'<NestedBaseUi value={{ ... }} content={node} />  |  <NestedBaseUi value={{ ... }}>{children}</NestedBaseUi>'}
+                returns="React context provider wrapper for internal nested-UI coordination."
+                props={{
+                    value: {
+                        description:
+                            "Optional extra context merged with the parent NestedBaseUi layer (if any), then with internal flags such as __hasParentUiComponent. Typo sets __typoPhrasingHost under phrasing-only hosts (e.g. Typo.p) so nested Typo.code maps to a <code> root instead of <pre>.",
+                        type: "object",
+                    },
+                    content: {
+                        description:
+                            "Preferred payload when the node may be a list or Fragment. Avoids React missing-key warnings that get attributed to NestedBaseUi when the same payload is passed as children. Typo uses this for phrasing hosts.",
+                        type: "ReactNode",
+                    },
+                    children: {
+                        description:
+                            "Nested UI subtree (single element preferred). Used by ScrollFlex / FloatingUi. Ignored when content is set.",
+                        type: "ReactNode",
+                    },
+                }}
+            />
+        </Ds.page>
+    );
+};
+
+export default X;

package/src/helpers/NestedBaseUi/index.jsx

@@ -0,0 +1,80 @@
+import { cloneElement, createContext, Fragment, isValidElement, useContext } from "react";
+
+const NestedBaseUiContext = createContext(null);
+
+export const NESTED_UI_TYPO_PHRASING_HOST = "__typoPhrasingHost";
+
+/** Works across yarn-link / dual-React copies (Fragment is Symbol.for). */
+const REACT_FRAGMENT_TYPE = Symbol.for("react.fragment");
+
+const isFragmentElement = (node) => isValidElement(node) && node.type === REACT_FRAGMENT_TYPE;
+
+const getNestedBaseUiContextValue = (parent = {}, extra = {}) => ({
+    ...parent,
+    ...extra,
+    __hasParentUiComponent: true,
+});
+
+export const useNestedBaseUiContext = () => useContext(NestedBaseUiContext) || {};
+
+/**
+ * Flatten Fragments and ensure every list item has a key.
+ * Re-parenting a Fragment whose children are an unkeyed element list makes React
+ * attribute the missing-key warning to NestedBaseUi — even when that Fragment is
+ * passed via `content` and wrapped in a span.
+ */
+const toKeyedHostChildren = (node, keyPrefix = "nested-ui") => {
+    if (node == null || node === false || node === true) return [];
+
+    if (isFragmentElement(node)) {
+        return toKeyedHostChildren(node.props?.children, keyPrefix);
+    }
+
+    if (Array.isArray(node)) {
+        const out = [];
+        node.forEach((child, index) => {
+            if (isFragmentElement(child)) {
+                out.push(...toKeyedHostChildren(child.props?.children, `${keyPrefix}-${index}`));
+                return;
+            }
+
+            if (isValidElement(child)) {
+                out.push(cloneElement(child, { key: child.key ?? `${keyPrefix}-${index}` }));
+                return;
+            }
+
+            if (child == null || child === false || child === true) return;
+
+            out.push(
+                <Fragment key={`${keyPrefix}-${index}`}>{child}</Fragment>,
+            );
+        });
+        return out;
+    }
+
+    if (isValidElement(node)) return [node];
+
+    return [<Fragment key={`${keyPrefix}-0`}>{node}</Fragment>];
+};
+
+/**
+ * Provider always gets exactly one child (display:contents span).
+ * Prefer `content` for list/Fragment payloads (Typo). `children` for single hosts
+ * (ScrollFlex, FloatingUi).
+ */
+const NestedBaseUi = ({ children, content, value }) => {
+    const parent = useNestedBaseUiContext();
+    const base = getNestedBaseUiContextValue(parent, value || {});
+    const node = content !== undefined ? content : children;
+    const hostChildren = toKeyedHostChildren(node);
+
+    return (
+        <NestedBaseUiContext.Provider value={base}>
+            <span style={{ display: "contents" }} data-nested-base-ui="">
+                {hostChildren.length <= 1 ? hostChildren[0] ?? null : hostChildren}
+            </span>
+        </NestedBaseUiContext.Provider>
+    );
+};
+
+export default NestedBaseUi;

package/src/helpers/NotifierListener/DefaultVariant.js

@@ -0,0 +1,47 @@
+import styled, { css } from "styled-components";
+
+export const DefaultVariant = styled.div`
+    ${({ theme, $bgColor, $colors }) => css`
+        position: relative;
+        display: grid;
+        grid-template-columns: 1fr 30rem;
+        grid-template-rows: 3rem 1fr;
+        width: 100%;
+        background: ${$bgColor || theme.background};
+        border-radius: 0 0 10rem 10rem;
+        overflow: hidden;
+
+        ${($bgColor || theme.background) &&
+        css`
+            color: ${$colors?.opposite || theme.foreground};
+        `}
+
+        & > [data-slot="timeBar"] {
+            position: relative;
+            grid-area: 1 / 1 / 2 / 3;
+            height: 3rem;
+            min-height: 3rem;
+            background: ${theme.colorAlpha(theme.primary, 0.5)};
+            overflow: hidden;
+
+            & > [data-slot="timeBarFill"] {
+                display: block;
+                height: 100%;
+                width: 100%;
+                transform: scaleX(0);
+                transform-origin: left center;
+                background: ${theme.primary};
+                will-change: transform;
+            }
+        }
+
+        & > [data-slot="close"] {
+            grid-area: 2 / 2 / 3 / 3;
+        }
+
+        & > [data-slot="content"] {
+            grid-area: 2 / 1 / 3 / 2;
+            padding: 10rem;
+        }
+    `}
+`;

package/src/helpers/NotifierListener/index.js

@@ -0,0 +1,3 @@
+import { Base } from "./tools/Base";
+
+export const NotifierListener = Base;

package/src/helpers/NotifierListener/tools/Base.jsx

@@ -0,0 +1,51 @@
+import { createPortal } from "react-dom";
+import S from "./_styled";
+import { useVars } from "./useVars";
+import { Box } from "./Box";
+import { ScrollFlex } from "libs/ScrollFlex";
+import { Flex } from "libs/Flex";
+
+export const Base = () => {
+    const { displayQueue, onExitComplete, theme, BoxComponent, openingMs } = useVars();
+
+    if (typeof document === "undefined") return null;
+    if (!displayQueue?.length) return null;
+
+    return createPortal(
+        <S.container aria-label="NotifierListener container">
+            <ScrollFlex.plain
+                width="100%"
+                height="100%"
+                autoWidth={false}
+                scrollBarProps={{
+                    disableX: true,
+                    fillMode: true,
+                    edgeMargin: 0,
+                    trackMargin: 0,
+                }}
+            >
+                <Flex.column
+                    gap={10}
+                    full
+                    width="100%"
+                    xAlign="stretch"
+                    paddingBottom={10}
+                    paddingLeft={6}
+                    paddingRight={6}
+                >
+                    {displayQueue.map((item) => (
+                        <Box
+                            key={item.queueId}
+                            item={item}
+                            BoxComponent={BoxComponent}
+                            theme={theme}
+                            openingMs={openingMs}
+                            onExitComplete={onExitComplete}
+                        />
+                    ))}
+                </Flex.column>
+            </ScrollFlex.plain>
+        </S.container>,
+        document.body,
+    );
+};

package/src/helpers/NotifierListener/tools/Box.jsx

@@ -0,0 +1,116 @@
+import { memo, useMemo, useRef, useLayoutEffect, useState, useCallback, useEffect } from "react";
+import S from "./_styled";
+import { TimeBar } from "./TimeBar";
+import { Button } from "libs/Button";
+import { colorGet } from "libs/colorGet";
+
+export const Box = memo(function Box({ item, BoxComponent, theme, openingMs, onExitComplete }) {
+    const {
+        bgColor,
+        value,
+        disableAutoKill,
+        remove,
+        killAfter,
+        status,
+        closingDelay,
+        shownAt,
+        queueId,
+    } = item || {};
+
+    const colors = useMemo(() => colorGet(bgColor || theme?.background), [bgColor, theme]);
+    const isClosing = status === "closing";
+    const closingDelayMs = Number(closingDelay) || 500;
+    const showTimeBar = !disableAutoKill;
+    const showClose = disableAutoKill;
+
+    const collapseRef = useRef(null);
+    const slotRef = useRef(null);
+    const [entered, setEntered] = useState(false);
+
+    const handleEnterEnd = useCallback(
+        (e) => {
+            if (entered || e.target !== e.currentTarget) return;
+            setEntered(true);
+        },
+        [entered],
+    );
+
+    useEffect(() => {
+        if (entered) return;
+        const timer = setTimeout(() => setEntered(true), openingMs + 50);
+        return () => clearTimeout(timer);
+    }, [entered, openingMs]);
+
+    useLayoutEffect(() => {
+        if (!isClosing) return;
+
+        const el = collapseRef.current;
+        const slotEl = slotRef.current;
+        if (!el) return;
+
+        const height = el.scrollHeight;
+
+        el.style.overflow = "hidden";
+        el.style.height = `${height}px`;
+        el.style.opacity = "1";
+        el.style.transition = "none";
+
+        if (slotEl) {
+            slotEl.style.transition = "none";
+            slotEl.style.marginBottom = `${10}rem`;
+        }
+
+        void el.offsetHeight;
+
+        el.style.transition = `height ${closingDelayMs}ms ease, opacity ${closingDelayMs}ms ease`;
+        el.style.height = "0px";
+        el.style.opacity = "0";
+
+        if (slotEl) {
+            slotEl.style.transition = `margin-bottom ${closingDelayMs}ms ease`;
+            slotEl.style.marginBottom = "0px";
+        }
+
+        const onEnd = (e) => {
+            if (e.target !== el || e.propertyName !== "height") return;
+            onExitComplete?.(queueId);
+        };
+
+        el.addEventListener("transitionend", onEnd);
+        return () => el.removeEventListener("transitionend", onEnd);
+    }, [isClosing, closingDelayMs, queueId, onExitComplete]);
+
+    return (
+        <S.slot ref={slotRef}>
+            <S.shell>
+                <S.collapse ref={collapseRef}>
+                    <S.slotInner
+                        $openingMs={openingMs}
+                        $entered={entered}
+                        onAnimationEnd={handleEnterEnd}
+                    >
+                        <BoxComponent
+                            $bgColor={colors?.color}
+                            $colors={colors}
+                            $closingDelay={closingDelayMs}
+                            $killAfter={killAfter}
+                            $disableAutoKill={disableAutoKill}
+                            $isClosing={isClosing}
+                            $status={status}
+                        >
+                            {showTimeBar && <TimeBar killAfterMs={killAfter} shownAt={shownAt} />}
+
+                            {showClose && (
+                                <div data-slot="close">
+                                    <Button.closeIcon onClick={remove} color={colors?.opposite} />
+                                </div>
+                            )}
+
+                            <div data-slot="content">{value}</div>
+                        </BoxComponent>
+                    </S.slotInner>
+                </S.collapse>
+            </S.shell>
+        </S.slot>
+    );
+});

package/src/helpers/NotifierListener/tools/TimeBar.jsx

@@ -0,0 +1,49 @@
+import { memo, useRef, useEffect } from "react";
+
+const TIMEBAR_KEYFRAMES_ID = "notifier-timebar-keyframes";
+
+const ensureTimeBarKeyframes = () => {
+    if (typeof document === "undefined") return;
+    if (document.getElementById(TIMEBAR_KEYFRAMES_ID)) return;
+
+    const style = document.createElement("style");
+    style.id = TIMEBAR_KEYFRAMES_ID;
+    style.textContent = `
+        @keyframes notifierTimeBarGrow {
+            from { transform: scaleX(0); }
+            to { transform: scaleX(1); }
+        }
+    `;
+    document.head.appendChild(style);
+};
+
+export const TimeBar = memo(
+    function TimeBar({ killAfterMs, shownAt }) {
+        const fillRef = useRef(null);
+
+        useEffect(() => {
+            ensureTimeBarKeyframes();
+            const el = fillRef.current;
+            if (!el || !killAfterMs) return;
+
+            const elapsed = Math.max(0, Date.now() - (shownAt || Date.now()));
+            const delaySec = Math.min(elapsed / 1000, killAfterMs / 1000);
+
+            el.style.transformOrigin = "left center";
+            el.style.transform = "scaleX(0)";
+            el.style.animation = "none";
+            void el.offsetWidth;
+            el.style.animation = `notifierTimeBarGrow ${killAfterMs}ms linear forwards`;
+            if (delaySec > 0) {
+                el.style.animationDelay = `-${delaySec}s`;
+            }
+        }, [killAfterMs, shownAt]);
+
+        return (
+            <div data-slot="timeBar">
+                <div ref={fillRef} data-slot="timeBarFill" />
+            </div>
+        );
+    },
+    (prev, next) => prev.killAfterMs === next.killAfterMs && prev.shownAt === next.shownAt,
+);

package/src/helpers/NotifierListener/tools/_styled.js

@@ -0,0 +1,74 @@
+import styled, { css, keyframes } from "styled-components";
+
+const enter = keyframes`
+    from {
+        transform: translateY(-20rem);
+    }
+    to {
+        transform: none;
+    }
+`;
+
+const S = {
+    container: styled.div`
+        position: fixed;
+        top: 0;
+        right: 0;
+        width: 300rem;
+        height: 100vh;
+        z-index: 2147483000;
+        padding: 10rem;
+        box-sizing: border-box;
+        pointer-events: none;
+        overflow: visible;
+        background: transparent;
+
+        [aria-label="ScrollFlex container"],
+        [aria-label="ScrollFlex shell"],
+        [aria-label="ScrollFlex content"] {
+            pointer-events: none;
+        }
+    `,
+
+    slot: styled.div`
+        width: 100%;
+        pointer-events: auto;
+        margin-bottom: 10rem;
+        background: transparent;
+
+        &:last-child {
+            margin-bottom: 0;
+        }
+    `,
+
+    collapse: styled.div`
+        width: 100%;
+        overflow: hidden;
+    `,
+
+    shell: styled.div`
+        ${({ theme }) => css`
+            width: 100%;
+            pointer-events: none;
+            border-radius: 0 0 10px 10px;
+            filter: drop-shadow(0 2px 2px ${theme.colorAlpha(theme.foreground, 0.5)});
+        `}
+    `,
+
+    slotInner: styled.div`
+        width: 100%;
+        ${({ $entered, $openingMs }) =>
+            !$entered &&
+            css`
+                animation: ${enter} ${$openingMs}ms ease forwards;
+            `}
+
+        ${({ $entered }) =>
+            $entered &&
+            css`
+                transform: none;
+            `}
+    `,
+};
+
+export default S;

package/src/helpers/NotifierListener/tools/useDisplayQueue.js

@@ -0,0 +1,85 @@
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+const pickSnapshot = (item) => ({
+    queueId: item.queueId,
+    bgColor: item.bgColor,
+    value: item.value,
+    disableAutoKill: item.disableAutoKill,
+    remove: item.remove,
+    killAfter: item.killAfter,
+    closingDelay: item.closingDelay,
+    status: item.status,
+    shownAt: item.shownAt,
+});
+
+const snapshotChanged = (a, b) => {
+    if (!a || !b) return true;
+    return (
+        a.status !== b.status ||
+        a.value !== b.value ||
+        a.bgColor !== b.bgColor ||
+        a.disableAutoKill !== b.disableAutoKill ||
+        a.killAfter !== b.killAfter ||
+        a.closingDelay !== b.closingDelay ||
+        a.shownAt !== b.shownAt
+    );
+};
+
+const mergeSnapshots = (prev, queue) => {
+    const next = { ...prev };
+    const queueIds = new Set();
+    let changed = false;
+
+    queue.forEach((item) => {
+        queueIds.add(item.queueId);
+        const incoming = pickSnapshot(item);
+        const existing = prev[item.queueId];
+
+        if (snapshotChanged(existing, incoming)) {
+            next[item.queueId] = incoming;
+            changed = true;
+        }
+    });
+
+    Object.keys(prev).forEach((key) => {
+        const id = Number(key);
+        if (!queueIds.has(id) && prev[id]?.status !== "closing") {
+            next[id] = { ...prev[id], status: "closing" };
+            changed = true;
+        }
+    });
+
+    return changed ? next : prev;
+};
+
+export const useDisplayQueue = (queue = []) => {
+    const [snapshots, setSnapshots] = useState({});
+
+    const queueToken = useMemo(
+        () =>
+            queue
+                .map((item) => `${item.queueId}:${item.status}:${String(item.value)}`)
+                .join("|"),
+        [queue],
+    );
+
+    useEffect(() => {
+        setSnapshots((prev) => mergeSnapshots(prev, queue));
+    }, [queueToken]);
+
+    const onExitComplete = useCallback((queueId) => {
+        setSnapshots((prev) => {
+            if (!prev[queueId]) return prev;
+            const next = { ...prev };
+            delete next[queueId];
+            return next;
+        });
+    }, []);
+
+    const displayQueue = useMemo(
+        () => Object.values(snapshots).filter((item) => item?.value),
+        [snapshots],
+    );
+
+    return { displayQueue, onExitComplete };
+};

package/src/helpers/NotifierListener/tools/useVars.js

@@ -0,0 +1,33 @@
+import { useMemo } from "react";
+import { baseStore } from "libs/baseStore";
+import { DefaultVariant } from "../DefaultVariant";
+import { useDisplayQueue } from "./useDisplayQueue";
+
+export const OPENING_MS = 500;
+
+export const useVars = () => {
+    const [_notifier, theme, projectSettings] = baseStore.useGlobal((s) => [
+        s._notifier,
+        s.theme,
+        s._projectSettings,
+    ]);
+
+    const { queue = [] } = _notifier || {};
+
+    const visibleQueue = useMemo(
+        () => (queue || []).filter((item) => item?.value),
+        [queue],
+    );
+
+    const { displayQueue, onExitComplete } = useDisplayQueue(visibleQueue);
+
+    const BoxComponent = projectSettings?.notifierSettings?.Box || DefaultVariant;
+
+    return {
+        displayQueue,
+        onExitComplete,
+        theme,
+        BoxComponent,
+        openingMs: OPENING_MS,
+    };
+};