@koslibs/components 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @koslibs/components
 
+## 1.2.0
+
+### Minor Changes
+
+- [#3](https://github.com/koslibs/components/pull/3) [`a618f52`](https://github.com/koslibs/components/commit/a618f526010adc6203a708e73fac3906b555ac78) Thanks [@holypower777](https://github.com/holypower777)! - Перенесён Popover из GullEye с отдельным импортом `@koslibs/components/Popover`,
+  стилями, Docs и Playground. Сохранены управляемая видимость, позиционирование,
+  ограничение размеров и способы закрытия. Портал и позиционирование адаптированы
+  для самостоятельного использования в React 18 и 19.
+
+    Popover управляет позицией и размерами и рендерит children напрямую. Оформление
+    и прокрутка содержимого задаются вызывающим компонентом; colors и contentClassName
+    не входят в API. Прежнее оформление Storybook-примеров сохранено в их содержимом.
+    Тень задаёт сам Popover через CSS-переменную --popover-shadow.
+    Offset по умолчанию равен `[0, 0]`, без смещения и зазора между якорем и содержимым.
+
+    Документация каждого компонента собрана в его папке docs: stories, страницы Docs
+    и стили примеров. Папки документации исключены из JS-сборки и деклараций npm-пакета.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -39,9 +39,11 @@ src/components/Button/
     index.ts
     button.tsx
     button.module.css
-    button.stories.tsx
-    button.docs.tsx
     CHANGELOG.md
+    docs/
+        button.stories.tsx
+        button.docs.tsx
+        examples.module.css
 ```
 
 1. Перенесите компонент в `src/components/<Name>`; имя папки — PascalCase, например `Button`.
@@ -59,7 +61,9 @@ src/components/Button/
     }
     ```
 
-4. Добавьте Docs, Playground и `CHANGELOG.md` по [примеру документации](https://github.com/koslibs/components/blob/main/docs/component-changelogs.md).
+4. Добавьте Docs и Playground в папку компонента `docs`, а `CHANGELOG.md` оставьте
+   рядом с реализацией, по [примеру документации](https://github.com/koslibs/components/blob/main/docs/component-changelogs.md).
+   Папки `src/**/docs` исключены из npm-сборки. Общие блоки Storybook находятся в `src/docs`.
 5. Добавьте тесты поведения. `npm run test:unit` запускает unit-тесты через
    `koslibs-builder lib:test`; `npm test` также проверяет отдельные импорты.
 6. Выполните сборку и проверьте реальные пути JS, деклараций и CSS в `dist`.

package/dist/components/Popover/components/popover-surface/index.d.ts

@@ -0,0 +1,4 @@
+import type { PopoverProps } from '../../types.js';
+export declare const PopoverSurface: import("react").ForwardRefExoticComponent<Omit<PopoverProps, "open" | "getPortalContainer" | "anchorElement"> & {
+    anchorElement: HTMLElement;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Popover/components/popover-surface/index.js

@@ -0,0 +1,106 @@
+import { jsx } from "react/jsx-runtime";
+import classnames from "classnames";
+import { forwardRef, useEffect, useImperativeHandle, useMemo, useState } from "react";
+import { createSizeModifier } from "../../create-size-modifier.js";
+import { usePopoverPosition } from "../../use-popover-position.js";
+import index_module from "../../index.module.js";
+const DEFAULT_OFFSET = [
+    0,
+    0
+];
+const PopoverSurface = /*#__PURE__*/ forwardRef(({ anchorElement, position = 'bottom-start', offset = DEFAULT_OFFSET, useAnchorWidth = false, preventFlip = false, fallbackPlacements, preventOverflow = true, availableHeight = true, viewportPadding = 8, onClose, outsideClick = true, escapeKeyDown = true, className, style, children, dataTestId, ...restProps }, ref)=>{
+    const [popperElement, setPopperElement] = useState(null);
+    useImperativeHandle(ref, ()=>popperElement, [
+        popperElement
+    ]);
+    const padding = Math.max(0, viewportPadding);
+    const modifiers = useMemo(()=>[
+            {
+                name: 'offset',
+                options: {
+                    offset
+                }
+            },
+            {
+                name: 'flip',
+                enabled: !preventFlip,
+                options: {
+                    fallbackPlacements,
+                    boundary: [],
+                    padding
+                }
+            },
+            {
+                name: 'preventOverflow',
+                enabled: preventOverflow,
+                options: {
+                    boundary: [],
+                    padding
+                }
+            },
+            createSizeModifier({
+                availableHeight,
+                useAnchorWidth,
+                viewportPadding: padding
+            })
+        ], [
+        offset,
+        preventFlip,
+        fallbackPlacements,
+        preventOverflow,
+        availableHeight,
+        useAnchorWidth,
+        padding
+    ]);
+    const { styles: popperStyles, attributes, update } = usePopoverPosition(anchorElement, popperElement, position, modifiers);
+    useEffect(()=>{
+        if (update) update();
+    }, [
+        children,
+        style,
+        update
+    ]);
+    useEffect(()=>{
+        if (!onClose) return;
+        const ownerDocument = anchorElement.ownerDocument;
+        const handlePointerDown = (event)=>{
+            if (event.defaultPrevented) return;
+            const path = event.composedPath();
+            if (path.includes(anchorElement) || popperElement && path.includes(popperElement)) return;
+            onClose();
+        };
+        const handleKeyDown = (event)=>{
+            if ('Escape' !== event.key || event.defaultPrevented) return;
+            event.preventDefault();
+            event.stopPropagation();
+            onClose();
+        };
+        if (outsideClick) ownerDocument.addEventListener('pointerdown', handlePointerDown);
+        if (escapeKeyDown) ownerDocument.addEventListener('keydown', handleKeyDown);
+        return ()=>{
+            ownerDocument.removeEventListener('pointerdown', handlePointerDown);
+            ownerDocument.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [
+        anchorElement,
+        popperElement,
+        onClose,
+        outsideClick,
+        escapeKeyDown
+    ]);
+    return /*#__PURE__*/ jsx("div", {
+        ...restProps,
+        ...attributes,
+        ref: setPopperElement,
+        className: classnames(index_module.component, className),
+        style: {
+            ...style,
+            ...popperStyles,
+            visibility: popperStyles?.transform ? style?.visibility : 'hidden'
+        },
+        "data-test-id": dataTestId,
+        children: children
+    });
+});
+PopoverSurface.displayName = 'PopoverSurface';
+export { PopoverSurface };

package/dist/components/Popover/create-size-modifier.d.ts

@@ -0,0 +1,8 @@
+import { type Modifier } from '@popperjs/core';
+type Options = {
+    availableHeight: boolean;
+    useAnchorWidth: boolean;
+    viewportPadding: number;
+};
+export declare const createSizeModifier: (options: Options) => Modifier<"availableSize", Options>;
+export {};

package/dist/components/Popover/create-size-modifier.js

@@ -0,0 +1,26 @@
+import { detectOverflow } from "@popperjs/core";
+const createSizeModifier = (options)=>({
+        name: 'availableSize',
+        enabled: true,
+        phase: 'beforeWrite',
+        requires: [
+            'computeStyles'
+        ],
+        options,
+        fn ({ state }) {
+            const { availableHeight, useAnchorWidth, viewportPadding } = options;
+            const documentElement = state.elements.popper.ownerDocument.documentElement;
+            const overflow = detectOverflow(state, {
+                boundary: [],
+                padding: viewportPadding
+            });
+            const side = state.placement.split('-')[0];
+            const height = 'top' === side || 'bottom' === side ? state.rects.popper.height - overflow[side] : documentElement.clientHeight - 2 * viewportPadding;
+            Object.assign(state.styles.popper, {
+                '--popover-viewport-padding': `${viewportPadding}px`,
+                '--popover-available-height': availableHeight ? `${Math.max(0, height)}px` : 'none'
+            });
+            if (useAnchorWidth) state.styles.popper.width = `${state.rects.reference.width}px`;
+        }
+    });
+export { createSizeModifier };

package/dist/components/Popover/index.d.ts

@@ -0,0 +1,2 @@
+export { Popover } from './popover.js';
+export type { PopoverProps, PopoverPosition } from './types.js';

package/dist/components/Popover/index.js

@@ -0,0 +1 @@
+export { Popover } from "./popover.js";

package/dist/components/Popover/index.module.js

@@ -0,0 +1,5 @@
+import "./index_module.css";
+const index_module = {
+    component: "component-wBbNPp"
+};
+export default index_module;

package/dist/components/Popover/index_module.css

@@ -0,0 +1,15 @@
+@import "./vars.css";
+
+.component-wBbNPp {
+  box-sizing: border-box;
+  z-index: var(--popover-z-index);
+  max-width: calc(100vw - var(--popover-viewport-padding, 8px) * 2);
+  min-width: 0;
+  min-height: 0;
+  max-height: var(--popover-available-height, none);
+  box-shadow: var(--popover-shadow);
+  flex-direction: column;
+  display: flex;
+  position: fixed;
+}
+

package/dist/components/Popover/popover.d.ts

@@ -0,0 +1,21 @@
+export type { PopoverProps, PopoverPosition } from './types.js';
+export declare const Popover: import("react").ForwardRefExoticComponent<Omit<import("react").HTMLAttributes<HTMLDivElement>, "className" | "style" | "children"> & {
+    children?: import("react").ReactNode;
+    className?: string;
+    style?: import("react").CSSProperties;
+    open: boolean;
+    anchorElement: HTMLElement | null;
+    position?: import("./types.js").PopoverPosition;
+    offset?: [number, number];
+    useAnchorWidth?: boolean;
+    preventFlip?: boolean;
+    fallbackPlacements?: import("./types.js").PopoverPosition[];
+    preventOverflow?: boolean;
+    availableHeight?: boolean;
+    viewportPadding?: number;
+    onClose?: VoidFunction;
+    outsideClick?: boolean;
+    escapeKeyDown?: boolean;
+    getPortalContainer?: () => Element | null;
+    dataTestId?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Popover/popover.js

@@ -0,0 +1,15 @@
+import { jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { createPortal } from "react-dom";
+import { PopoverSurface } from "./components/popover-surface/index.js";
+const Popover = /*#__PURE__*/ forwardRef(({ open, anchorElement, getPortalContainer, ...restProps }, ref)=>{
+    if (!open || !anchorElement) return null;
+    const container = getPortalContainer ? getPortalContainer() : anchorElement.ownerDocument.body;
+    return container ? /*#__PURE__*/ createPortal(/*#__PURE__*/ jsx(PopoverSurface, {
+        ...restProps,
+        anchorElement: anchorElement,
+        ref: ref
+    }), container) : null;
+});
+Popover.displayName = 'Popover';
+export { Popover };

package/dist/components/Popover/types.d.ts

@@ -0,0 +1,86 @@
+import type { Placement } from '@popperjs/core';
+import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
+export type PopoverPosition = Exclude<Placement, 'auto' | 'auto-start' | 'auto-end'>;
+export type PopoverProps = Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'className' | 'style'> & {
+    /** Содержимое поповера. Оформление и прокрутка задаются вызывающим компонентом. */
+    children?: ReactNode;
+    /**
+     * Дополнительный класс внешнего контейнера.
+     */
+    className?: string;
+    /**
+     * Стили внешнего контейнера, включая ширину.
+     */
+    style?: CSSProperties;
+    /**
+     * Видимость поповера.
+     */
+    open: boolean;
+    /**
+     * Элемент, относительно которого открывается поповер.
+     */
+    anchorElement: HTMLElement | null;
+    /**
+     * Предпочтительная позиция относительно элемента.
+     * @default 'bottom-start'
+     */
+    position?: PopoverPosition;
+    /**
+     * Смещение вдоль элемента и расстояние от него, в пикселях.
+     * @default [0, 0]
+     */
+    offset?: [number, number];
+    /**
+     * Использовать ширину элемента, относительно которого открыт поповер.
+     * @default false
+     */
+    useAnchorWidth?: boolean;
+    /**
+     * Запретить смену стороны при недостатке места.
+     * @default false
+     */
+    preventFlip?: boolean;
+    /**
+     * Позиции, которые проверяются при недостатке места.
+     */
+    fallbackPlacements?: PopoverPosition[];
+    /**
+     * Удерживать поповер в пределах видимой области.
+     * @default true
+     */
+    preventOverflow?: boolean;
+    /**
+     * Ограничивать высоту доступным местом.
+     * Для прокрутки задайте содержимому min-height: 0 и overflow: auto.
+     * @default true
+     */
+    availableHeight?: boolean;
+    /**
+     * Минимальный отступ от границ видимой области, в пикселях.
+     * @default 8
+     */
+    viewportPadding?: number;
+    /**
+     * Обработчик запроса закрытия. Обновите open в вызывающем компоненте.
+     */
+    onClose?: VoidFunction;
+    /**
+     * Разрешить закрытие по нажатию вне поповера и его элемента.
+     * @default true
+     */
+    outsideClick?: boolean;
+    /**
+     * Разрешить закрытие по Escape.
+     * @default true
+     */
+    escapeKeyDown?: boolean;
+    /**
+     * Контейнер портала. По умолчанию — body документа anchorElement.
+     * Если функция возвращает null, поповер не рендерится.
+     */
+    getPortalContainer?: () => Element | null;
+    /**
+     * Идентификатор для автоматизированных тестов.
+     */
+    dataTestId?: string;
+};

package/dist/components/Popover/use-popover-position.d.ts

@@ -0,0 +1,8 @@
+import { type Modifier } from '@popperjs/core';
+import { type CSSProperties } from 'react';
+import type { PopoverPosition } from './types.js';
+export declare function usePopoverPosition(anchorElement: HTMLElement, popperElement: HTMLDivElement | null, position: PopoverPosition, modifiers: Partial<Modifier<string, object>>[]): {
+    update: () => Promise<Partial<import("@popperjs/core").State>> | undefined;
+    styles: CSSProperties;
+    attributes: Record<string, string | boolean>;
+};

package/dist/components/Popover/use-popover-position.js

@@ -0,0 +1,78 @@
+import { createPopper } from "@popperjs/core";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+const initialState = {
+    styles: {
+        position: 'fixed',
+        left: 0,
+        top: 0,
+        visibility: 'hidden'
+    },
+    attributes: {}
+};
+function usePopoverPosition(anchorElement, popperElement, position, modifiers) {
+    const [state, setState] = useState(initialState);
+    const instanceRef = useRef(null);
+    const updateState = useMemo(()=>({
+            name: 'reactStyles',
+            enabled: true,
+            phase: 'write',
+            requires: [
+                'computeStyles'
+            ],
+            fn: ({ state: popperState })=>{
+                setState({
+                    styles: {
+                        ...popperState.styles.popper
+                    },
+                    attributes: {
+                        ...popperState.attributes.popper
+                    }
+                });
+            }
+        }), []);
+    useEffect(()=>{
+        if (!popperElement) return;
+        let active = true;
+        setState(initialState);
+        const instance = createPopper(anchorElement, popperElement, {
+            placement: position,
+            strategy: 'fixed',
+            modifiers: [
+                ...modifiers,
+                {
+                    ...updateState,
+                    fn: (args)=>{
+                        if (active) updateState.fn(args);
+                    }
+                },
+                {
+                    name: 'applyStyles',
+                    enabled: false
+                }
+            ]
+        });
+        instanceRef.current = instance;
+        const ResizeObserverClass = anchorElement.ownerDocument.defaultView?.ResizeObserver;
+        const observer = ResizeObserverClass ? new ResizeObserverClass(()=>void instance.update()) : void 0;
+        observer?.observe(anchorElement);
+        observer?.observe(popperElement);
+        return ()=>{
+            active = false;
+            observer?.disconnect();
+            instance.destroy();
+            instanceRef.current = null;
+        };
+    }, [
+        anchorElement,
+        popperElement,
+        position,
+        modifiers,
+        updateState
+    ]);
+    const update = useCallback(()=>instanceRef.current?.update(), []);
+    return {
+        ...state,
+        update
+    };
+}
+export { usePopoverPosition };

package/dist/components/Popover/vars.css

@@ -0,0 +1,5 @@
+:root {
+  --popover-z-index: 1100;
+  --popover-shadow: 0 8px 24px #00000029;
+}
+

package/dist/index.d.ts

@@ -4,3 +4,5 @@ export { Spinner } from './components/Spinner/index.js';
 export type { SpinnerProps } from './components/Spinner/index.js';
 export { Typography, TypographyText, TypographyTitle, Text, Title } from './components/Typography/index.js';
 export type { TextProps, TitleProps, TypographyColor, TypographyWeight, } from './components/Typography/index.js';
+export { Popover } from './components/Popover/index.js';
+export type { PopoverProps, PopoverPosition } from './components/Popover/index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export { Button } from "./components/Button/index.js";
 export { Spinner } from "./components/Spinner/index.js";
 export { Text, Title, Typography, TypographyText, TypographyTitle } from "./components/Typography/index.js";
+export { Popover } from "./components/Popover/index.js";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@koslibs/components",
-    "version": "1.1.0",
+    "version": "1.2.0",
     "description": "Shared React components for koslibs projects",
     "type": "module",
     "main": "./dist/index.js",
@@ -80,6 +80,7 @@
         "react-dom": "^18.3.1 || ^19.0.0"
     },
     "dependencies": {
+        "@popperjs/core": "2.11.8",
         "classnames": "2.5.1"
     }
 }