@koslibs/components 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @koslibs/components
 
+## 1.3.0
+
+### Minor Changes
+
+- [#4](https://github.com/koslibs/components/pull/4) [`b37f3b0`](https://github.com/koslibs/components/commit/b37f3b008be8ffea80908557c13ea77d6d55c792) Thanks [@holypower777](https://github.com/holypower777)! - Перенесён Collapse из core-components GullEye с отдельным импортом
+  `@koslibs/components/Collapse`, внутренним и внешним управлением, сохранением
+  содержимого, анимацией и поддержкой reduced motion. Проп `colors` убран:
+  оформление кнопки настраивается через CSS-переменные. Добавлены документация
+  с тремя вкладками, Playground и история компонента. Стрелка подключается
+  отдельным импортом из `@koslibs/icons`.
+
+    Подписи `collapsedLabel` и `expandedLabel` не имеют дефолтных значений.
+    Добавлены `showRightChevron` (по умолчанию `true`) и `showLeftChevron`
+    (по умолчанию `false`): можно независимо показывать шевроны или скрыть оба.
+    Левый шеврон смотрит вправо в закрытом состоянии и вниз в раскрытом,
+    правый сохраняет поворот вниз → вверх.
+
+    Комментарии публичных пропсов приведены к единому многострочному формату JSDoc
+    с отдельной строкой для `@default`.
+
+## 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/Collapse/collapse.d.ts

@@ -0,0 +1,91 @@
+import { type HTMLAttributes, type ReactNode } from 'react';
+export type CollapseProps = Omit<HTMLAttributes<HTMLDivElement>, 'onTransitionEnd'> & {
+    /**
+     * Состояние controlled-компонента.
+     */
+    expanded?: boolean;
+    /**
+     * Начальное состояние uncontrolled-компонента.
+     * @default false
+     */
+    defaultExpanded?: boolean;
+    /**
+     * Подпись кнопки, когда содержимое скрыто.
+     */
+    collapsedLabel?: ReactNode;
+    /**
+     * Подпись кнопки, когда содержимое раскрыто.
+     */
+    expandedLabel?: ReactNode;
+    /**
+     * Показывать шеврон справа от подписи: вниз при закрытии, вверх при раскрытии.
+     * @default true
+     */
+    showRightChevron?: boolean;
+    /**
+     * Показывать шеврон слева от подписи: вправо при закрытии, вниз при раскрытии.
+     * @default false
+     */
+    showLeftChevron?: boolean;
+    /**
+     * Запрос изменения состояния. В controlled-режиме обновите expanded.
+     */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Завершение раскрытия/сворачивания; без анимации вызывается сразу.
+     */
+    onTransitionEnd?: (expanded: boolean) => void;
+    /**
+     * Дополнительный класс внутреннего контейнера содержимого.
+     */
+    expandedContentClassName?: string;
+    /**
+     * Идентификатор корневого элемента для автоматизированных тестов.
+     */
+    dataTestId?: string;
+};
+export declare const Collapse: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "onTransitionEnd"> & {
+    /**
+     * Состояние controlled-компонента.
+     */
+    expanded?: boolean;
+    /**
+     * Начальное состояние uncontrolled-компонента.
+     * @default false
+     */
+    defaultExpanded?: boolean;
+    /**
+     * Подпись кнопки, когда содержимое скрыто.
+     */
+    collapsedLabel?: ReactNode;
+    /**
+     * Подпись кнопки, когда содержимое раскрыто.
+     */
+    expandedLabel?: ReactNode;
+    /**
+     * Показывать шеврон справа от подписи: вниз при закрытии, вверх при раскрытии.
+     * @default true
+     */
+    showRightChevron?: boolean;
+    /**
+     * Показывать шеврон слева от подписи: вправо при закрытии, вниз при раскрытии.
+     * @default false
+     */
+    showLeftChevron?: boolean;
+    /**
+     * Запрос изменения состояния. В controlled-режиме обновите expanded.
+     */
+    onExpandedChange?: (expanded: boolean) => void;
+    /**
+     * Завершение раскрытия/сворачивания; без анимации вызывается сразу.
+     */
+    onTransitionEnd?: (expanded: boolean) => void;
+    /**
+     * Дополнительный класс внутреннего контейнера содержимого.
+     */
+    expandedContentClassName?: string;
+    /**
+     * Идентификатор корневого элемента для автоматизированных тестов.
+     */
+    dataTestId?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/Collapse/collapse.js

@@ -0,0 +1,103 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { ChevronDownIcon } from "@koslibs/icons/ChevronDownIcon";
+import classnames from "classnames";
+import { forwardRef, useId, useLayoutEffect, useRef, useState } from "react";
+import index_module from "./index.module.js";
+const Collapse = /*#__PURE__*/ forwardRef(({ expanded, defaultExpanded = false, collapsedLabel, expandedLabel, showRightChevron = true, showLeftChevron = false, onExpandedChange, onTransitionEnd, expandedContentClassName, dataTestId, className, children, ...restProps }, ref)=>{
+    const [expandedState, setExpandedState] = useState(defaultExpanded);
+    const isExpanded = expanded ?? expandedState;
+    const contentId = `collapse-${useId()}`;
+    const contentRef = useRef(null);
+    const innerRef = useRef(null);
+    const toggleRef = useRef(null);
+    const previousExpanded = useRef(isExpanded);
+    const pendingTransition = useRef(false);
+    const transitionCallback = useRef(onTransitionEnd);
+    const label = isExpanded ? expandedLabel || collapsedLabel : collapsedLabel || expandedLabel;
+    useLayoutEffect(()=>{
+        transitionCallback.current = onTransitionEnd;
+    }, [
+        onTransitionEnd
+    ]);
+    useLayoutEffect(()=>{
+        const content = contentRef.current;
+        if (!content) return;
+        if (!isExpanded && content.contains(content.ownerDocument.activeElement)) toggleRef.current?.focus();
+        content.inert = !isExpanded;
+        if (previousExpanded.current === isExpanded) return;
+        previousExpanded.current = isExpanded;
+        pendingTransition.current = true;
+        const transitionDuration = content.ownerDocument.defaultView?.getComputedStyle(content).transitionDuration;
+        if (innerRef.current?.scrollHeight === 0 || 0 === parseFloat(transitionDuration ?? '0')) {
+            pendingTransition.current = false;
+            transitionCallback.current?.(isExpanded);
+        }
+    }, [
+        isExpanded
+    ]);
+    const handleToggle = ()=>{
+        const nextExpanded = !isExpanded;
+        if (void 0 === expanded) setExpandedState(nextExpanded);
+        onExpandedChange?.(nextExpanded);
+    };
+    const handleTransitionEnd = (event)=>{
+        if (event.target === event.currentTarget && 'grid-template-rows' === event.propertyName && pendingTransition.current) {
+            pendingTransition.current = false;
+            transitionCallback.current?.(isExpanded);
+        }
+    };
+    return /*#__PURE__*/ jsxs("div", {
+        ...restProps,
+        ref: ref,
+        className: classnames(index_module.component, className),
+        "data-test-id": dataTestId,
+        children: [
+            label && /*#__PURE__*/ jsxs("button", {
+                ref: toggleRef,
+                type: "button",
+                className: index_module.toggle,
+                "aria-expanded": isExpanded,
+                "aria-controls": contentId,
+                onClick: handleToggle,
+                "data-test-id": dataTestId ? `${dataTestId}-toggle` : void 0,
+                children: [
+                    showLeftChevron && /*#__PURE__*/ jsx(ChevronDownIcon, {
+                        className: classnames(index_module.icon, index_module.leftIcon, {
+                            [index_module.rotated]: isExpanded
+                        }),
+                        "aria-hidden": "true"
+                    }),
+                    /*#__PURE__*/ jsx("span", {
+                        children: label
+                    }),
+                    showRightChevron && /*#__PURE__*/ jsx(ChevronDownIcon, {
+                        className: classnames(index_module.icon, {
+                            [index_module.rotated]: isExpanded
+                        }),
+                        "aria-hidden": "true"
+                    })
+                ]
+            }),
+            /*#__PURE__*/ jsx("div", {
+                ref: contentRef,
+                id: contentId,
+                className: classnames(index_module.content, {
+                    [index_module.expanded]: isExpanded
+                }),
+                "aria-hidden": !isExpanded,
+                "data-test-id": dataTestId ? `${dataTestId}-content` : void 0,
+                onTransitionEnd: handleTransitionEnd,
+                children: /*#__PURE__*/ jsx("div", {
+                    className: index_module.clip,
+                    children: /*#__PURE__*/ jsx("div", {
+                        ref: innerRef,
+                        className: expandedContentClassName,
+                        children: children
+                    })
+                })
+            })
+        ]
+    });
+});
+Collapse.displayName = 'Collapse';
+export { Collapse };

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

@@ -0,0 +1,2 @@
+export { Collapse } from './collapse.js';
+export type { CollapseProps } from './collapse.js';

package/dist/components/Collapse/index.js

@@ -0,0 +1 @@
+export { Collapse } from "./collapse.js";

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

@@ -0,0 +1,12 @@
+import "./index_module.css";
+const index_module = {
+    component: "component-tPiInR",
+    content: "content-D8E_z9",
+    expanded: "expanded-rqGMOG",
+    clip: "clip-D3ydtQ",
+    toggle: "toggle-YA8uJB",
+    icon: "icon-wFeaQN",
+    rotated: "rotated-sRw5l2",
+    leftIcon: "leftIcon-PGZrVM"
+};
+export default index_module;

package/dist/components/Collapse/index_module.css

@@ -0,0 +1,82 @@
+@import "../../styles/theme.css";
+@import "./vars.css";
+
+.component-tPiInR {
+  min-width: 0;
+  font-family: var(--font-primary);
+}
+
+.content-D8E_z9 {
+  visibility: hidden;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows .2s, visibility 0s linear .2s;
+  display: grid;
+}
+
+.expanded-rqGMOG {
+  visibility: visible;
+  grid-template-rows: 1fr;
+  transition-delay: 0s;
+}
+
+.clip-D3ydtQ {
+  min-height: 0;
+  overflow: hidden;
+}
+
+.toggle-YA8uJB {
+  align-items: center;
+  gap: var(--size-4, 4px);
+  max-width: 100%;
+  padding: var(--size-8, 8px) 0;
+  color: var(--collapse-color);
+  font: inherit;
+  text-align: left;
+  overflow-wrap: anywhere;
+  cursor: pointer;
+  background: none;
+  border: 0;
+  margin: 0;
+  font-size: 13px;
+  line-height: 20px;
+  display: inline-flex;
+
+  &:hover {
+    color: var(--collapse-hover-color);
+  }
+
+  &:hover span {
+    text-underline-offset: 3px;
+    text-decoration: underline;
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--collapse-focus-color);
+    outline-offset: 2px;
+    border-radius: var(--border-radius-4, 4px);
+  }
+}
+
+.icon-wFeaQN {
+  flex-shrink: 0;
+  transition: transform .2s;
+}
+
+.rotated-sRw5l2 {
+  transform: rotate(180deg);
+}
+
+.leftIcon-PGZrVM {
+  transform: rotate(-90deg);
+
+  &.rotated-sRw5l2 {
+    transform: rotate(0);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .content-D8E_z9, .icon-wFeaQN {
+    transition: none;
+  }
+}
+

package/dist/components/Collapse/vars.css

@@ -0,0 +1,6 @@
+:root {
+  --collapse-color: #1c1a18;
+  --collapse-hover-color: #686d63;
+  --collapse-focus-color: #7967f2;
+}
+

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,88 @@
+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/components/Typography/shared.d.ts

@@ -2,11 +2,17 @@ import type { CSSProperties, HTMLAttributes, ReactNode } from 'react';
 export type TypographyWeight = 'regular' | 'medium' | 'semibold' | 'bold';
 export type TypographyColor = 'inherit' | 'primary' | 'secondary' | 'inverse' | 'positive' | 'negative';
 export type BaseProps = Omit<HTMLAttributes<HTMLElement>, 'color' | 'children' | 'className' | 'style'> & {
-    /** Содержимое текста или заголовка. */
+    /**
+     * Содержимое текста или заголовка.
+     */
     children?: ReactNode;
-    /** Дополнительный CSS-класс корневого элемента. */
+    /**
+     * Дополнительный CSS-класс корневого элемента.
+     */
     className?: string;
-    /** Инлайн-стили корневого элемента. */
+    /**
+     * Инлайн-стили корневого элемента.
+     */
     style?: CSSProperties;
     /**
      * Цвет текста. По умолчанию наследуется от родителя.

package/dist/index.d.ts

@@ -4,3 +4,7 @@ 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';
+export { Collapse } from './components/Collapse/index.js';
+export type { CollapseProps } from './components/Collapse/index.js';

package/dist/index.js

@@ -1,3 +1,5 @@
 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";
+export { Collapse } from "./components/Collapse/index.js";

package/package.json

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