@rolder/kit 3.0.0-alpha.7 → 3.0.0-alpha.8

package/src/ui/scrollArea/README.md

@@ -0,0 +1,369 @@
+# ScrollArea Component
+
+Расширенная область прокрутки с автоматическим скроллом и интеллектуальным управлением позиционированием на базе Mantine ScrollArea.
+
+## Установка
+
+Компонент уже включен в kit компонентов:
+
+```tsx
+import { ScrollArea, useScrollArea } from "@/components/kit";
+```
+
+## Базовое использование
+
+### Простая прокручиваемая область
+
+```tsx
+import { ScrollArea } from "@/components/kit";
+
+function BasicExample() {
+  return (
+    <ScrollArea h={300}>
+      <div>
+        {Array.from({ length: 50 }, (_, i) => (
+          <div key={i} style={{ padding: "10px" }}>
+            Элемент {i + 1}
+          </div>
+        ))}
+      </div>
+    </ScrollArea>
+  );
+}
+```
+
+### Чат с автоскроллом
+
+```tsx
+import { ScrollArea } from "@/components/kit";
+
+function ChatMessages({ messages }) {
+  return (
+    <ScrollArea
+      autoScroll
+      scrollToBottomOnInit
+      animated
+      nearThreshold={100}
+      h={400}
+    >
+      {messages.map((msg) => (
+        <div
+          key={msg.id}
+          style={{ padding: "8px", borderBottom: "1px solid #eee" }}
+        >
+          <strong>{msg.author}:</strong> {msg.text}
+        </div>
+      ))}
+
+      <ScrollArea.ScrollButton className="absolute bottom-4 right-4 z-10" />
+    </ScrollArea>
+  );
+}
+```
+
+## API
+
+### Важно понимать:
+
+- **ScrollArea** автоматически оборачивает `children` в `ScrollArea.Content`
+- **ScrollArea.Content** нужен только когда требуется ref на прокручиваемую область
+- **ScrollArea.ScrollButton** работает везде внутри ScrollArea через контекст
+
+### ScrollArea Props
+
+Наследует все пропсы от Mantine ScrollArea плюс дополнительные:
+
+| Prop                   | Type               | Default | Описание                                        |
+| ---------------------- | ------------------ | ------- | ----------------------------------------------- |
+| `autoScroll`           | `boolean`          | `false` | Включение автоскролла при добавлении контента   |
+| `scrollToBottomOnInit` | `boolean`          | `false` | Прокрутить к концу при инициализации компонента |
+| `animated`             | `boolean`          | `true`  | Анимированная прокрутка                         |
+| `nearThreshold`        | `number`           | `100`   | Отступ для near-зон в пикселях                  |
+| `h`                    | `string \| number` | -       | Высота области прокрутки                        |
+| `scrollbarSize`        | `number`           | -       | Размер полосы прокрутки                         |
+| `type`                 | `string`           | -       | Тип поведения полос прокрутки                   |
+| `...mantineProps`      | -                  | -       | Все остальные пропсы Mantine ScrollArea         |
+
+### Доступ к viewport элементу
+
+Используйте `useScrollArea` для получения ref на прокручиваемую область:
+
+```tsx
+function MyComponent() {
+  const { viewportRef } = useScrollArea();
+
+  const scrollToElement = () => {
+    const target = viewportRef.current?.querySelector("[data-target]");
+    target?.scrollIntoView();
+  };
+
+  const getScrollPosition = () => {
+    console.log("Scroll top:", viewportRef.current?.scrollTop);
+    console.log("Scroll height:", viewportRef.current?.scrollHeight);
+  };
+
+  return (
+    <ScrollArea h={400}>
+      <div data-target>Элемент для прокрутки</div>
+      <button onClick={scrollToElement}>Прокрутить к элементу</button>
+      <button onClick={getScrollPosition}>Получить позицию</button>
+    </ScrollArea>
+  );
+}
+```
+
+### ScrollArea.ScrollButton Props
+
+✅ **Работает везде внутри ScrollArea** - использует контекст, не требует Content.
+
+| Prop        | Type        | Default               | Описание                   |
+| ----------- | ----------- | --------------------- | -------------------------- |
+| `className` | `string`    | -                     | CSS классы                 |
+| `upIcon`    | `ReactNode` | `<IconChevronUp />`   | Иконка для прокрутки вверх |
+| `downIcon`  | `ReactNode` | `<IconChevronDown />` | Иконка для прокрутки вниз  |
+
+#### Примеры размещения:
+
+```tsx
+// В любом месте внутри ScrollArea
+<ScrollArea h={400}>
+  {content}
+  <ScrollArea.ScrollButton className="absolute bottom-4 right-4" />
+</ScrollArea>
+
+// Даже вложенно
+<ScrollArea h={400}>
+  <div className="relative">
+    {content}
+    <ScrollArea.ScrollButton />
+  </div>
+</ScrollArea>
+
+// Или в начале
+<ScrollArea h={400}>
+  <ScrollArea.ScrollButton className="mb-4" />
+  {content}
+</ScrollArea>
+```
+
+## Контекст
+
+### useScrollArea
+
+Хук для доступа к состоянию и методам ScrollArea:
+
+```tsx
+import { ScrollArea, useScrollArea } from "@/components/kit";
+
+function CustomControls() {
+  const {
+    isAtTop,
+    isNearTop,
+    isAtBottom,
+    isNearBottom,
+    isAboveCenter,
+    hasScrollableContent,
+    scrollToTop,
+    scrollToBottom,
+    viewportRef,
+  } = useScrollArea();
+
+  return (
+    <div>
+      <button onClick={() => scrollToTop()} disabled={isAtTop}>
+        В начало
+      </button>
+
+      <button onClick={() => scrollToBottom()} disabled={isAtBottom}>
+        В конец
+      </button>
+
+      {hasScrollableContent && (
+        <span>{isAboveCenter ? "Верхняя половина" : "Нижняя половина"}</span>
+      )}
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <ScrollArea>
+      {/* контент */}
+      <CustomControls />
+    </ScrollArea>
+  );
+}
+```
+
+### Состояния позиции
+
+- `isAtTop`: точно в начале (scrollTop === 0)
+- `isNearTop`: в пределах nearThreshold от начала
+- `isAtBottom`: точно в конце
+- `isNearBottom`: в пределах nearThreshold от конца
+- `isAboveCenter`: выше центральной точки
+- `hasScrollableContent`: есть контент для прокрутки
+
+### Методы управления
+
+- `scrollToTop(animated?: boolean)`: прокрутить к началу
+- `scrollToBottom(animated?: boolean)`: прокрутить к концу
+- `viewportRef`: React RefObject на viewport элемент для прямого доступа
+
+## Логика автоскролла
+
+### Автоскролл при инициализации
+
+Выполняется когда:
+
+- `autoScroll === true`
+- `scrollToBottomOnInit === true`
+- Есть прокручиваемый контент
+
+### Автоскролл при добавлении контента
+
+Выполняется когда:
+
+- `autoScroll === true`
+- `isAtBottom === true` (точное позиционирование!)
+- Нет активного взаимодействия пользователя
+
+## Примеры использования
+
+### Логи в реальном времени
+
+```tsx
+function LogViewer({ logs }) {
+  return (
+    <ScrollArea
+      autoScroll
+      h={500}
+      style={{ fontFamily: "monospace", fontSize: "12px" }}
+    >
+      {logs.map((log, index) => (
+        <div key={index} style={{ padding: "2px 8px" }}>
+          <span style={{ color: "#666" }}>{log.timestamp}</span>
+          <span
+            style={{
+              color:
+                log.level === "error"
+                  ? "red"
+                  : log.level === "warn"
+                    ? "orange"
+                    : "inherit",
+            }}
+          >
+            {log.message}
+          </span>
+        </div>
+      ))}
+    </ScrollArea>
+  );
+}
+```
+
+### Список с кастомными контролами
+
+```tsx
+function ItemsList({ items }) {
+  return (
+    <ScrollArea nearThreshold={50} h={400}>
+      {items.map((item) => (
+        <div
+          key={item.id}
+          style={{ padding: "12px", borderBottom: "1px solid #eee" }}
+        >
+          {item.name}
+        </div>
+      ))}
+
+      <div style={{ position: "absolute", top: "10px", right: "10px" }}>
+        <CustomScrollControls />
+      </div>
+    </ScrollArea>
+  );
+}
+
+function CustomScrollControls() {
+  const { scrollToTop, scrollToBottom, hasScrollableContent } = useScrollArea();
+
+  if (!hasScrollableContent) return null;
+
+  return (
+    <div style={{ display: "flex", gap: "8px" }}>
+      <button onClick={() => scrollToTop()}>↑</button>
+      <button onClick={() => scrollToBottom()}>↓</button>
+    </div>
+  );
+}
+```
+
+### Комбинация с другими компонентами
+
+```tsx
+import { ScrollArea } from "@/components/kit";
+import { Button, Text, Badge } from "@mantine/core";
+
+function NotificationCenter({ notifications }) {
+  return (
+    <ScrollArea autoScroll maxH={300} p="md">
+      {notifications.length === 0 ? (
+        <Text c="dimmed" ta="center" py="xl">
+          Нет уведомлений
+        </Text>
+      ) : (
+        notifications.map((notification) => (
+          <div key={notification.id} style={{ marginBottom: "12px" }}>
+            <div
+              style={{
+                display: "flex",
+                justifyContent: "space-between",
+                alignItems: "center",
+              }}
+            >
+              <Text size="sm" fw={500}>
+                {notification.title}
+              </Text>
+              <Badge
+                size="xs"
+                color={notification.priority === "high" ? "red" : "blue"}
+              >
+                {notification.priority}
+              </Badge>
+            </div>
+            <Text size="xs" c="dimmed" mt={4}>
+              {notification.message}
+            </Text>
+          </div>
+        ))
+      )}
+    </ScrollArea>
+  );
+}
+```
+
+## Стилизация
+
+Компонент полностью совместим с системой стилизации Mantine. Вы можете передавать все стандартные Mantine пропсы через `ScrollArea.Content`:
+
+```tsx
+<ScrollArea
+  h={400}
+  p="md"
+  style={{ backgroundColor: "#f8f9fa" }}
+  scrollbarSize={6}
+  scrollHideDelay={1500}
+  type="hover"
+>
+  {/* контент */}
+</ScrollArea>
+```
+
+## Производительность
+
+Компонент оптимизирован для производительности:
+
+- Дебаунсинг событий скролла (16ms для 60fps)
+- Оптимальное отслеживание изменений размера через ResizeObserver
+- Минимальные ререндеры благодаря правильной мемоизации
+- Автоматическая очистка event listeners и таймеров

package/{dist/ui/scrollArea/ScrollArea.d.ts → src/ui/scrollArea/ScrollArea.tsx}

@@ -1,4 +1,41 @@
+import { ScrollAreaProvider } from './context';
+import { ScrollAreaButton } from './ScrollAreaButton';
+import { ScrollAreaContent } from './ScrollAreaContent';
 import type { ScrollAreaContextValue, ScrollAreaProps } from './types';
+import { useScrollAreaState } from './useScrollArea';
+
+const ScrollAreaRoot = ({
+  children,
+  autoScroll = false,
+  scrollToBottomOnInit = false,
+  animated = true,
+  nearThreshold = 100,
+  radius,
+  ...mantineProps
+}: ScrollAreaProps) => {
+  const scrollAreaValue = useScrollAreaState({
+    autoScroll,
+    scrollToBottomOnInit,
+    animated,
+    nearThreshold,
+  });
+
+  // Создаем контекст с mantineProps
+  const contextValue: ScrollAreaContextValue = {
+    ...scrollAreaValue,
+    radius,
+    mantineProps,
+  };
+
+  return (
+    <ScrollAreaProvider value={contextValue}>
+      <ScrollAreaContent>{children}</ScrollAreaContent>
+    </ScrollAreaProvider>
+  );
+};
+
+ScrollAreaRoot.displayName = 'ScrollArea';
+
 /**
  * ScrollArea Component - Расширенная область прокрутки с автоскроллом
  *
@@ -50,13 +87,7 @@ import type { ScrollAreaContextValue, ScrollAreaProps } from './types';
  *   );
  * }
  */
-export declare const ScrollArea: {
-    ({ children, autoScroll, scrollToBottomOnInit, animated, nearThreshold, radius, ...mantineProps }: ScrollAreaProps): import("react/jsx-runtime").JSX.Element;
-    displayName: string;
-} & {
-    ScrollButton: {
-        ({ className }: import("./types").ScrollButtonProps): import("react/jsx-runtime").JSX.Element | null;
-        displayName: string;
-    };
-    Provider: import("react").Provider<ScrollAreaContextValue | null>;
-};
+export const ScrollArea = Object.assign(ScrollAreaRoot, {
+  ScrollButton: ScrollAreaButton,
+  Provider: ScrollAreaProvider,
+});

package/src/ui/scrollArea/ScrollAreaButton.tsx

@@ -0,0 +1,56 @@
+import { ActionIcon } from '@mantine/core';
+import { useScrollArea } from './context';
+import type { ScrollButtonProps } from './types';
+
+export const ScrollAreaButton = ({ className }: ScrollButtonProps) => {
+  const { hasScrollableContent, isAboveCenter, scrollToTop, scrollToBottom } =
+    useScrollArea();
+
+  // Не показываем кнопку, если нет прокручиваемого контента
+  if (!hasScrollableContent) return null;
+
+  const isScrollingDown = isAboveCenter;
+  const icon = (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      role="img"
+      aria-label="Chevron"
+      style={{
+        transition: 'transform 0.2s ease-in-out',
+        transform: isScrollingDown ? 'rotate(-180deg)' : 'rotate(0deg)',
+      }}
+    >
+      <path stroke="none" d="M0 0h24v24H0z" fill="none" />
+      <path d="M6 9l6 6l6 -6" />
+    </svg>
+  );
+
+  const handleClick = () => {
+    if (isScrollingDown) scrollToBottom();
+    else scrollToTop();
+  };
+
+  return (
+    <ActionIcon
+      pos="absolute"
+      bottom={16}
+      right={16}
+      variant="light"
+      onClick={handleClick}
+      className={className}
+      aria-label={isScrollingDown ? 'Scroll to bottom' : 'Scroll to top'}
+    >
+      {icon}
+    </ActionIcon>
+  );
+};
+
+ScrollAreaButton.displayName = 'ScrollArea.ScrollButton';

package/src/ui/scrollArea/ScrollAreaContent.tsx

@@ -0,0 +1,36 @@
+import { Box, getRadius, ScrollArea as MantineScrollArea } from '@mantine/core';
+import { useContext } from 'react';
+import { ScrollAreaContext } from './context';
+
+export const ScrollAreaContent = ({
+  children,
+}: {
+  children: React.ReactNode;
+}) => {
+  // Получаем полное состояние из контекста (включая внутренние детали)
+  const fullContext = useContext(ScrollAreaContext);
+  if (!fullContext) {
+    throw new Error('ScrollAreaContent must be used within ScrollArea');
+  }
+
+  const { _callbackRef, mantineProps, radius, _contentResizeRef } = fullContext;
+
+  return (
+    <MantineScrollArea
+      classNames={{
+        viewport: 'rolder-scroll-area-viewport',
+        content: 'rolder-scroll-area-content',
+        scrollbar: 'rolder-scroll-area-scrollbar',
+      }}
+      style={{ '--radius': radius ? getRadius(radius) : undefined }}
+      {...mantineProps}
+      viewportRef={_callbackRef}
+    >
+      <Box h="100%" w="100%" ref={_contentResizeRef}>
+        {children}
+      </Box>
+    </MantineScrollArea>
+  );
+};
+
+ScrollAreaContent.displayName = 'ScrollArea.Content';

package/{dist/ui/scrollArea/context.d.ts → src/ui/scrollArea/context.tsx}

@@ -1,7 +1,13 @@
+import { createContext, useContext } from 'react';
 import type { ScrollAreaContextValue, ScrollAreaHook } from './types';
+
 /** Внутренний контекст для передачи состояния ScrollArea */
-export declare const ScrollAreaContext: import("react").Context<ScrollAreaContextValue | null>;
-export declare const ScrollAreaProvider: import("react").Provider<ScrollAreaContextValue | null>;
+export const ScrollAreaContext = createContext<ScrollAreaContextValue | null>(
+  null,
+);
+
+export const ScrollAreaProvider = ScrollAreaContext.Provider;
+
 /**
  * Хук для доступа к состоянию и методам ScrollArea
  *
@@ -25,4 +31,13 @@ export declare const ScrollAreaProvider: import("react").Provider<ScrollAreaCont
  * }
  * ```
  */
-export declare const useScrollArea: () => ScrollAreaHook;
+export const useScrollArea = (): ScrollAreaHook => {
+  const context = useContext(ScrollAreaContext);
+  if (!context) {
+    throw new Error('useScrollArea must be used within ScrollArea');
+  }
+
+  // Возвращаем только публичный API, скрывая внутренние детали
+  const { _callbackRef, mantineProps: _, radius: __, ...publicAPI } = context;
+  return publicAPI;
+};

package/src/ui/scrollArea/index.ts

@@ -0,0 +1,10 @@
+export { useScrollArea } from './context';
+export { ScrollArea } from './ScrollArea';
+export type {
+  ScrollAreaContextValue,
+  ScrollAreaHook,
+  ScrollAreaProps,
+  ScrollAreaState,
+  ScrollButtonProps,
+  ScrollPosition,
+} from './types';

package/src/ui/scrollArea/types.ts

@@ -0,0 +1,77 @@
+import type {
+  MantineRadius,
+  ScrollAreaProps as MantineScrollAreaProps,
+} from '@mantine/core';
+import type { ReactNode } from 'react';
+
+export interface ScrollAreaProps
+  extends Omit<MantineScrollAreaProps, 'children'> {
+  /** Включение автоскролла при добавлении контента (по умолчанию false) */
+  autoScroll?: boolean;
+  /** Прокрутить к концу при инициализации компонента (по умолчанию false) */
+  scrollToBottomOnInit?: boolean;
+  /** Анимированная прокрутка (по умолчанию true) */
+  animated?: boolean;
+  /** Отступ для near-зон в пикселях (по умолчанию 100) */
+  nearThreshold?: number;
+  /** Радиус для viewport и scrollbar на тот случай, когда они "торчат" углами*/
+  radius?: MantineRadius;
+  /** Дочерние элементы - автоматически оборачиваются в ScrollArea.Content */
+  children: ReactNode;
+}
+
+export interface ScrollAreaHook {
+  /** Точно в начале (scrollTop === 0) */
+  isAtTop: boolean;
+  /** В пределах nearThreshold от начала */
+  isNearTop: boolean;
+  /** Точно в конце (scrollTop + clientHeight >= scrollHeight) */
+  isAtBottom: boolean;
+  /** В пределах nearThreshold от конца */
+  isNearBottom: boolean;
+  /** Выше центральной точки области прокрутки */
+  isAboveCenter: boolean;
+  /** Есть контент требующий прокрутки */
+  hasScrollableContent: boolean;
+
+  /** Прокрутить к началу области */
+  scrollToTop: (animated?: boolean) => void;
+  /** Прокрутить к концу области */
+  scrollToBottom: (animated?: boolean) => void;
+
+  /** React ref на viewport элемент для прямого доступа к DOM */
+  viewportRef: React.RefObject<HTMLDivElement | null>;
+}
+
+export interface ScrollAreaState extends ScrollAreaHook {
+  /** Внутренний callback ref для подключения к Mantine ScrollArea */
+  _callbackRef: (node: HTMLDivElement | null) => void;
+  /** Внутренний ref для наблюдения за изменениями контента */
+  _contentResizeRef: (node: HTMLDivElement | null) => void;
+}
+
+export interface ScrollAreaContextValue extends ScrollAreaState {
+  /** Радиус для viewport и scrollbar на тот случай, когда они "торчат" углами*/
+  radius?: MantineRadius;
+  /** Пропсы Mantine ScrollArea, переданные в корневой компонент */
+  mantineProps: Omit<MantineScrollAreaProps, 'children'>;
+}
+
+export interface ScrollButtonProps {
+  /** CSS классы для стилизации кнопки */
+  className?: string;
+  /** Иконка для прокрутки вверх (по умолчанию IconChevronUp) */
+  upIcon?: ReactNode;
+  /** Иконка для прокрутки вниз (по умолчанию IconChevronDown) */
+  downIcon?: ReactNode;
+}
+
+/** Внутренний тип для отслеживания позиции скролла */
+export interface ScrollPosition {
+  /** Текущая позиция скролла сверху */
+  scrollTop: number;
+  /** Высота видимой области */
+  clientHeight: number;
+  /** Общая высота прокручиваемого контента */
+  scrollHeight: number;
+}