@idem.agency/popups-engine 0.0.9

package/README.md

@@ -0,0 +1,176 @@
+# Popups-engine
+
+Движок для управления попапами в React с поддержкой кастомных компонентов и анимаций через `motion`.
+
+Версия `motion`: **^12.24.7**
+
+## Установка
+
+```bash
+npm i @barabel324/popups-engine
+```
+
+## Основные компоненты
+
+### PopupsEngineProvider
+
+Провайдер для регистрации и управления попапами.
+
+```tsx
+<PopupsEngineProvider popups={popups}>
+  {children}
+
+  <PopupsEngineRoot
+    id="popups-root"
+    lockBodyScroll={() => (document.body.style.overflow = 'hidden')}
+    enableBodyScroll={() => (document.body.style.overflow = '')}
+  />
+</PopupsEngineProvider>
+```
+
+### PopupsEngineRoot
+
+Компонент, который рендерит все попапы и обёртки. Обычно используется один раз в корне приложения.
+
+```tsx
+<PopupsEngineRoot
+  id="popups-root"
+  lockBodyScroll={() => (document.body.style.overflow = 'hidden')}
+  enableBodyScroll={() => (document.body.style.overflow = '')}
+/>
+```
+
+#### Пропсы
+
+| Проп               | Тип                 | Описание                                                           |
+| ------------------ | ------------------- | ------------------------------------------------------------------ |
+| `id`               | `string`            | `id` атрибут для корневого элемента попапов                        |
+| `lockBodyScroll`   | `() => void`        | Функция блокировки скролла страницы                                |
+| `enableBodyScroll` | `() => void`        | Функция разблокировки скролла страницы                             |
+| `components`       | `TPEComponents`     | Кастомные компоненты. `openPopup` имеет приоритет над этим пропсом |
+| `classNames`       | `TPEClassNames`     | Кастомные классы. `openPopup` имеет приоритет над этим пропсом     |
+| `motionVariants`   | `TPEMotionVariants` | Анимации для `motion`-обёртки попапа. `openPopup` имеет приоритет  |
+
+`PopupsEngineProvider` должен оборачивать приложение, а `PopupsEngineRoot` должен быть отрендерен внутри него.
+
+## Хук usePopupsEngineProvider
+
+Позволяет управлять попапами внутри компонентов.
+
+```ts
+const {
+  openPopup,
+  closePopup,
+  closeFirstPopup,
+  closeAllPopups,
+} = usePopupsEngineProvider();
+
+openPopup({ variant: 'MyPopup', popupProps: { title: 'Hello' } });
+closePopup();
+closeFirstPopup();
+closeAllPopups();
+```
+
+### Пропсы openPopup
+
+| Проп             | Тип                   | Описание                                                               |
+| ---------------- | --------------------- | ---------------------------------------------------------------------- |
+| `variant`        | `string`              | Ключ попапа, зарегистрированного в провайдере                          |
+| `popupProps`     | `Record<string, any>` | Пропсы, передаваемые в компонент попапа                                |
+| `isCloseAll`     | `boolean`             | Закрывать ли все попапы при вызове `close` внутри попапа               |
+| `components`     | `TPEComponents`       | Кастомные компоненты. Приоритет над `PopupsEngineRoot`                 |
+| `classNames`     | `TPEClassNames`       | Кастомные классы. Приоритет над `PopupsEngineRoot`                     |
+| `motionVariants` | `TPEMotionVariants`   | Анимации для `motion`-обёртки попапа. Приоритет над `PopupsEngineRoot` |
+
+## Кастомизация
+
+Кастомизация возможна глобально через `PopupsEngineRoot` или локально через `openPopup`.
+
+Пропсы, переданные в `openPopup`, имеют приоритет над пропсами `PopupsEngineRoot`.
+
+### Компоненты
+
+```tsx
+const components = {
+  wrapper: CustomWrapper,
+  loader: CustomLoader,
+};
+```
+
+### Классы
+
+```tsx
+const classNames = {
+  wrapper: 'my-wrapper-class',
+  loader: 'my-loader-class',
+};
+```
+
+## Анимации (motion / framer-motion)
+
+```tsx
+const motionVariants = {
+  initial: { opacity: 0, y: -20 },
+  animate: { opacity: 1, y: 0 },
+  exit: { opacity: 0, y: 20 },
+};
+```
+
+## Дженерики
+
+`TPEComponentWrapper` — дженерик для типизации попапов. Библиотека автоматически передаёт в компонент служебные пропсы (например, `closePopup`).
+
+## Минимальный пример
+
+```tsx
+// '@/popup-templates/message'
+export const PopupMessage: TPEComponentWrapper<TPopupMessage> = ({
+  title,
+  description,
+  closePopup,
+}) => (
+  <div>
+    <div>{title}</div>
+    <div>{description}</div>
+    <button type="button" onClick={closePopup}>
+      close
+    </button>
+  </div>
+);
+
+// '@/popup-templates'
+const popups = {
+  message: lazy(() => import('@views/popup-templates/message')),
+};
+
+// '@/show-popup'
+export const ShowPopup = () => {
+  const { openPopup } = usePopupsEngineProvider();
+
+  return (
+    <button
+      type="button"
+      onClick={() =>
+        openPopup({
+          variant: 'message',
+          popupProps: {
+            title: 'I am popup',
+            description: 'Destroyer of the worlds',
+          },
+        })
+      }
+    >
+      Press
+    </button>
+  );
+};
+
+// 'app.tsx'
+import { PopupsEngineProvider, PopupsEngineRoot } from '@barabel324/popups-engine';
+import '@barabel324/popups-engine/css';
+
+<PopupsEngineProvider popups={popups}>
+  <ShowPopup />
+  <PopupsEngineRoot />
+</PopupsEngineProvider>
+```

package/dist/css.d.ts

@@ -0,0 +1,2 @@
+declare const css: string;
+export default css;

package/dist/popups-engine.css

@@ -0,0 +1 @@
+._parent_wmksm_1{z-index:100;position:fixed;inset:0;display:flex;align-items:center;justify-content:center;width:100%;height:100vh;background-color:#00000080}._parent_1ud1o_1{color:#fff}

package/dist/popups-engine.d.ts

@@ -0,0 +1,119 @@
+import { Variant } from 'motion/react';
+
+/** Утилитарный дженерик для обозначения функционального компонента с пропсами children и className */
+declare type FCClass<P = object> = React.FC<P & React.PropsWithChildren & {
+    className?: string;
+}>;
+
+export declare const PopupsEngineProvider: FCClass<TPEProvider>;
+
+export declare const PopupsEngineRoot: FCClass<TPERoot>;
+
+declare type TPEClassNames = {
+    [K in keyof TPEMapComponents]?: TPEMapComponents[K]['className'];
+};
+
+declare type TPEComponents = {
+    [K in keyof TPEMapComponents]?: TPEMapComponents[K]['component'];
+};
+
+/** Дженерик для частного попапа. Либа передает некоторые методы пропсом в попап, который прокидывают в провайдер */
+export declare type TPEComponentWrapper<K = object> = FCClass<{
+    /** Закрыть последний попап */
+    closePopup: () => void;
+} & K>;
+
+/** Контекст методов */
+declare type TPEContext = {
+    /** Открыть попап */
+    openPopup: (data: TPEExecute) => void;
+    /** Закрыть последний попап */
+    closePopup: () => void;
+    /** Закрыть первый попап */
+    closeFirstPopup: () => void;
+    /** Закрыть все попапы */
+    closeAllPopups: () => void;
+};
+
+/**
+ * пропсы openPopup
+ */
+declare type TPEExecute = {
+    /** вариант попапа (берется из ключей объекта, переданного в провайдер) */
+    variant: string;
+    /** пропсы попапа, который хотят вызывать */
+    popupProps?: Record<string, any>;
+    /** закрыть ли все попапы, если вызвать пропс close, переданный в попап */
+    isCloseAll?: boolean;
+    /** кастомные компоненты либы */
+    components?: TPEComponents;
+    /** кастомные классы для компонентов либы */
+    classNames?: TPEClassNames;
+    /** Варианты анимации обертки для motion */
+    motionVariants?: TPEMotionVariants;
+};
+
+declare type TPEMapComponents = {
+    /** обертка, в которую ставится попап */
+    wrapper: {
+        /** компонент обертки */
+        component: TPEWrapper;
+        /** класс обертки */
+        className: string;
+    };
+    /** лоудер, который отображается, когда лези попап грузится (Suspense fallback) */
+    loader: {
+        /** компонент лоудера */
+        component: FCClass;
+        /** класс лоудера */
+        className: string;
+    };
+};
+
+/**
+ * Варианты анимации обертки для motion
+ */
+declare type TPEMotionVariants = {
+    /** Начальное положение обертки */
+    initial: Variant;
+    /** Активное положение обертки */
+    animate: Variant;
+    /** Анимация ухода обертки */
+    exit: Variant;
+};
+
+/** провайдер для открытия попаов */
+declare type TPEProvider = {
+    /** частные попапы */
+    popups: Record<string, FCClass<any>>;
+};
+
+/** Рут для попапов */
+declare type TPERoot = {
+    /** аттрибут id рута */
+    id?: string;
+    /** кастомные компоненты либы */
+    components?: TPEComponents;
+    /** кастомные классы для компонентов либы */
+    classNames?: TPEClassNames;
+    /** Варианты анимации обертки для motion */
+    motionVariants?: TPEMotionVariants;
+    /** Каллбак для вызова разрешающего метода скролл лока */
+    enableBodyScroll?: () => void;
+    /** Каллбак для вызова запрещающего метода скролл лока */
+    lockBodyScroll?: () => void;
+};
+
+/**
+ * Компонент обертки
+ */
+declare type TPEWrapper = FCClass<{
+    /**
+     * Варианты анимации обертки для motion
+     */
+    motionVariants?: TPEMotionVariants;
+}>;
+
+export declare const usePopupsEngineProvider: () => TPEContext;
+
+export { }

package/dist/popups-engine.js

@@ -0,0 +1,152 @@
+import { jsx as n } from "react/jsx-runtime";
+import { createContext as g, useContext as x, useRef as O, useEffect as y, Suspense as R, useState as $, useCallback as b, useMemo as f } from "react";
+import { motion as j, AnimatePresence as F } from "motion/react";
+const L = g({
+  openPopup: () => {
+  },
+  closePopup: () => {
+  },
+  closeFirstPopup: () => {
+  },
+  closeAllPopups: () => {
+  }
+}), k = g({
+  popupList: []
+}), A = g({
+  popups: {}
+}), V = () => x(L), I = () => x(k), S = () => x(A), z = "_parent_wmksm_1", K = {
+  parent: z
+}, M = {
+  initial: { opacity: 0 },
+  animate: { opacity: 1 },
+  exit: { opacity: 0 }
+}, q = ({
+  className: o,
+  motionVariants: u = M,
+  children: p
+}) => {
+  const t = O(null), { closePopup: r } = V(), i = (c) => {
+    c.target === t.current && r();
+  };
+  return /* @__PURE__ */ n(
+    j.div,
+    {
+      variants: u,
+      initial: "initial",
+      animate: "animate",
+      exit: "exit",
+      ref: t,
+      className: o ?? K.parent,
+      onClick: i,
+      children: p
+    }
+  );
+}, G = "_parent_1ud1o_1", H = {
+  parent: G
+}, J = ({
+  className: o
+}) => /* @__PURE__ */ n(
+  "div",
+  {
+    className: o ?? H.parent,
+    children: "Loading..."
+  }
+), W = ({
+  className: o,
+  id: u = "popups-engine-root",
+  components: p,
+  classNames: t,
+  motionVariants: r,
+  enableBodyScroll: i,
+  lockBodyScroll: c
+}) => {
+  const { popupList: s } = I(), { popups: v } = S(), { closePopup: l, closeAllPopups: P } = V();
+  return y(() => (s.length > 0 && c?.(), () => {
+    s.length > 0 && i?.();
+  }), [
+    s,
+    i,
+    c
+  ]), y(() => {
+    const e = (m) => {
+      m.key === "Escape" && (s.at(-1)?.isCloseAll ? P : l)();
+    };
+    return s.length > 0 && window.addEventListener("keydown", e), () => {
+      window.removeEventListener("keydown", e);
+    };
+  }, [
+    s,
+    l,
+    P
+  ]), /* @__PURE__ */ n(
+    "div",
+    {
+      className: o,
+      id: u,
+      children: /* @__PURE__ */ n(F, { children: s.map((e) => {
+        const {
+          popupID: m,
+          variant: a,
+          popupProps: E,
+          isCloseAll: d,
+          components: w,
+          classNames: C,
+          motionVariants: _
+        } = e, N = w?.wrapper || p?.wrapper || q, D = w?.loader || p?.loader || J, h = v[a];
+        return h ? /* @__PURE__ */ n(
+          N,
+          {
+            className: C?.wrapper || t?.wrapper,
+            motionVariants: _ || r,
+            children: /* @__PURE__ */ n(
+              R,
+              {
+                fallback: /* @__PURE__ */ n(D, { className: C?.loader || t?.loader }),
+                children: /* @__PURE__ */ n(
+                  h,
+                  {
+                    ...E,
+                    closePopup: d ? P : l
+                  }
+                )
+              }
+            )
+          },
+          m
+        ) : null;
+      }) })
+    }
+  );
+}, X = ({
+  popups: o,
+  children: u
+}) => {
+  const [p, t] = $([]), r = b((e) => {
+    const m = Object.keys(o), { variant: a } = e;
+    a && (m.some((d) => d === a) ? t((d) => [...d, {
+      ...e,
+      popupID: Date.now()
+    }]) : console.error(`there are no "${a}" popup`));
+  }, [o]), i = () => {
+    t((e) => e.slice(0, -1));
+  }, c = () => {
+    t((e) => e.slice(1));
+  }, s = () => {
+    t(() => []);
+  }, v = f(() => ({
+    openPopup: r,
+    closePopup: i,
+    closeFirstPopup: c,
+    closeAllPopups: s
+  }), [r]), l = f(() => ({
+    popupList: p
+  }), [p]), P = f(() => ({
+    popups: o
+  }), [o]);
+  return /* @__PURE__ */ n(L.Provider, { value: v, children: /* @__PURE__ */ n(k.Provider, { value: l, children: /* @__PURE__ */ n(A.Provider, { value: P, children: u }) }) });
+};
+export {
+  X as PopupsEngineProvider,
+  W as PopupsEngineRoot,
+  V as usePopupsEngineProvider
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@idem.agency/popups-engine",
+  "version": "0.0.9",
+  "author": "@barabel324",
+  "type": "module",
+  "main": "./dist/popups-engine.js",
+  "types": "./dist/popups-engine.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/popups-engine.js"
+    },
+    "./css": {
+      "import": "./dist/popups-engine.css",
+      "types": "./dist/css.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "lintFix": "eslint . --fix",
+    "preview": "vite preview",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "motion": "12.24.7",
+    "react": "19.2.3",
+    "react-dom": "19.2.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "9.39.2",
+    "@microsoft/api-extractor": "7.55.2",
+    "@stylistic/eslint-plugin": "5.7.0",
+    "@types/node": "25.0.9",
+    "@types/react": "19.2.9",
+    "@types/react-dom": "19.2.3",
+    "@vitejs/plugin-react": "5.1.2",
+    "eslint": "9.39.2",
+    "eslint-plugin-react-hooks": "7.0.1",
+    "eslint-plugin-react-refresh": "0.4.26",
+    "globals": "17.0.0",
+    "motion": "12.27.3",
+    "react": "19.2.3",
+    "react-dom": "19.2.3",
+    "sass-embedded": "1.97.2",
+    "typescript": "5.9.3",
+    "typescript-eslint": "8.53.1",
+    "unplugin-dts": "1.0.0-beta.6",
+    "vite": "7.3.1"
+  },
+  "gitHead": "0a18b8cd441ad4a319fc8a3b536246b8c42a84be"
+}