hallo-kit 0.3.0 → 0.3.1

package/src/ui/data-list/data-list.tsx

@@ -1,331 +1,331 @@
-'use client'
-
-import * as React from 'react'
-
-import { useWindowVirtualizer } from '@tanstack/react-virtual'
-
-import { Card } from '../card'
-import { Separator } from '../separator'
-import { useRevealOnce } from '../../hooks/useRevealOnce'
-import { cn } from '../../lib/utils'
-
-// data-list — примитив «разделённый список строк» (то, что в макете выглядит как
-// «таблица», но без шапки и колонок). Владеет общим каркасом: Card-оболочка,
-// вертикальные паддинги строк, разделители, скелетон-режим. Над списком — window-
-// виртуализация (@tanstack/react-virtual): на длинных списках в DOM живут только
-// видимые строки. Высота строк РАЗНАЯ (2–3 текст-линии) → меряем по факту
-// (measureElement). Стили — свои (у Radix примитива списка/таблицы нет, как и для
-// Card/Badge). Контент строки и его скелетон задаёт фича через renderItem/renderSkeleton.
-
-// useLayoutEffect на сервере шумит предупреждением → на SSR падаем в useEffect.
-const useIsoLayoutEffect =
-	typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect
-
-// Вариант каркаса списка:
-// - 'divided' (деф.) — один Card-конверт, строки разделены ui/Separator (то, что в макете
-//   выглядит как «таблица»);
-// - 'separated' — каждая строка отдельной Card с вертикальным зазором между ними (список
-//   карточек). Внешнего Card-конверта нет.
-export type DataListVariant = 'divided' | 'separated'
-
-// Каркас одной строки. Поведение зависит от variant.
-//
-// divided: Card-конверт без своего паддинга (p-0!) — все отступы задаёт строка:
-// - ui/Separator между строками (центрирован: mx-auto + 95% ширины);
-// - по бокам у всех px-fl-16/20; вертикаль между строками 11/15.
-//   Разделитель внутри строки → меряется вместе с ней (один код-путь для потока и
-//   виртуализации). hoverable → подсветка фона на наведение (full-bleed, Card без p).
-//
-// separated: строка = отдельная Card (свой паддинг/скругление). Зазор — pt у строк, кроме
-//   первой; паддинг ВХОДИТ в box → measureElement учитывает его и при виртуализации.
-//   hoverable → Card.interactive (курсор + подсветка рамки + лёгкое нажатие).
-//
-// ref как проп (React 19) — для measureElement виртуализатора.
-function RowFrame({
-	index,
-	// count в API строки оставлен (симметрия с index, нужен кастомным вариантам),
-	// но текущие варианты его не используют — вынимаем из ...props, чтобы не утёк в DOM.
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	count: _count,
-	variant = 'divided',
-	hoverable = false,
-	className,
-	children,
-	ref,
-	...props
-}: React.ComponentProps<'div'> & {
-	index: number
-	count: number
-	variant?: DataListVariant
-	hoverable?: boolean
-}) {
-	if (variant === 'separated') {
-		return (
-			<div
-				ref={ref}
-				className={cn(index > 0 && 'pt-fl-8/10', className)}
-				{...props}
-			>
-				<Card interactive={hoverable}>{children}</Card>
-			</div>
-		)
-	}
-
-	return (
-		<div ref={ref} className={className} {...props}>
-			{index > 0 && <Separator className='mx-auto w-[96%]!' />}
-			<div
-				className={cn(
-					'px-fl-16/20',
-					'py-fl-11/15',
-
-					hoverable && 'rounded-md transition-colors hover:bg-accent',
-				)}
-			>
-				{children}
-			</div>
-		</div>
-	)
-}
-
-export interface DataListProps<T> {
-	/** Данные. `undefined` = идёт загрузка → рисуем скелетон-строки. */
-	items: readonly T[] | undefined
-	/** Стабильный ключ строки. */
-	getKey: (item: T, index: number) => React.Key
-	/** Содержимое строки (обычно фичевый *-row компонент). */
-	renderItem: (item: T, index: number) => React.ReactNode
-	/** Содержимое скелетон-строки (тот же *-row без данных). */
-	renderSkeleton?: (index: number) => React.ReactNode
-	/** Сколько скелетон-строк показать при загрузке. */
-	skeletonCount?: number
-	/** Стартовая оценка высоты строки, px (дальше меряется по факту). */
-	estimateSize?: number
-	/** С какого размера списка включать виртуализацию. */
-	virtualizeThreshold?: number
-	/** Запас строк сверху/снизу видимой области. */
-	overscan?: number
-	/** Что показать, когда данные пришли, но список пуст. */
-	empty?: React.ReactNode
-	/** Подсветка строки на наведение (по умолчанию включена). */
-	hoverable?: boolean
-	/**
-	 * Вид списка: `divided` (деф.) — один Card с разделителями между строками;
-	 * `separated` — каждая строка отдельной Card с зазором между ними.
-	 */
-	variant?: DataListVariant
-	/**
-	 * Ключ одноразового каскада появления строк (reveal-stagger): первый показ за сессию —
-	 * строки всплывают лесенкой, повторный заход — список сразу. Без ключа каскада нет.
-	 * На виртуализированном списке каскад не играет (transform строк занят позиционированием).
-	 */
-	revealKey?: string
-	className?: string
-}
-
-export function DataList<T>({
-	items,
-	getKey,
-	renderItem,
-	renderSkeleton,
-	skeletonCount = 5,
-	estimateSize = 64,
-	virtualizeThreshold = 40,
-	overscan = 6,
-	empty,
-	hoverable = true,
-	variant = 'divided',
-	revealKey,
-	className,
-}: DataListProps<T>) {
-	const loading = items === undefined
-	const count = items?.length ?? 0
-	const shouldVirtualize = count > virtualizeThreshold
-	// Одноразовый каскад появления строк. Значение фиксируется на маунте: если компонент
-	// смонтировался в загрузке (скелетоны), каскад сыграет на приходе данных.
-	const revealPlay = useRevealOnce(revealKey)
-
-	// Внешний конверт списка: divided — единый Card (строки несут отступы сами, p-0!);
-	// separated — обычный блок, отступы и фон у каждой строки-Card. Это ФУНКЦИЯ-хелпер,
-	// а не компонент: вызываем как frame(...), иначе новый тип на каждый рендер ремаунтил
-	// бы всё поддерево (ломая виртуализацию/фокус).
-	const frame = (children: React.ReactNode) =>
-		variant === 'separated' ? (
-			<div className={cn('flex flex-col', className)}>{children}</div>
-		) : (
-			<Card className={cn('gap-0! p-0!', className)}>{children}</Card>
-		)
-
-	// Смещение списка от верха документа — scrollMargin для window-виртуализатора.
-	// Меряем после монтирования (и на resize); до этого виртуализация не активна.
-	const listRef = React.useRef<HTMLDivElement>(null)
-	const [scrollMargin, setScrollMargin] = React.useState(0)
-	useIsoLayoutEffect(() => {
-		if (!shouldVirtualize) return
-		const measure = () => {
-			if (listRef.current) {
-				setScrollMargin(
-					listRef.current.getBoundingClientRect().top + window.scrollY,
-				)
-			}
-		}
-		measure()
-		window.addEventListener('resize', measure)
-		return () => window.removeEventListener('resize', measure)
-	}, [shouldVirtualize])
-
-	// Хук вызываем всегда (правила хуков); при count=0 он по сути выключен.
-	const virtualizer = useWindowVirtualizer({
-		count: shouldVirtualize ? count : 0,
-		estimateSize: () => estimateSize,
-		overscan,
-		scrollMargin,
-	})
-
-	// — Загрузка: skeletonCount строк-заглушек (всегда в потоке, их мало).
-	if (loading) {
-		return frame(
-			Array.from({ length: skeletonCount }).map((_, i) => (
-				<RowFrame key={i} index={i} count={skeletonCount} variant={variant}>
-					{renderSkeleton?.(i)}
-				</RowFrame>
-			)),
-		)
-	}
-
-	// — Пусто.
-	if (count === 0) {
-		return empty ? frame(empty) : null
-	}
-
-	// — Короткий список: обычный поток, без оверхеда виртуализации. Каскад появления —
-	// только здесь (см. revealKey): reveal всплывает строку, задержка растёт до 10-й,
-	// дальше плато, чтобы длинный список не тянулся.
-	if (!shouldVirtualize) {
-		return frame(
-			items!.map((item, i) => (
-				<RowFrame
-					key={getKey(item, i)}
-					index={i}
-					count={count}
-					variant={variant}
-					hoverable={hoverable}
-					className={revealPlay ? 'reveal' : undefined}
-					style={
-						revealPlay
-							? { animationDelay: `${Math.min(i, 10) * 35}ms` }
-							: undefined
-					}
-				>
-					{renderItem(item, i)}
-				</RowFrame>
-			)),
-		)
-	}
-
-	// — Длинный список: window-виртуализация. В DOM только видимые строки, спейсер
-	// держит общую высоту, строки позиционируются translateY от измеренных позиций.
-	const virtualItems = virtualizer.getVirtualItems()
-	return frame(
-		<div
-			ref={listRef}
-			className='relative w-full'
-			style={{ height: virtualizer.getTotalSize() }}
-		>
-			{virtualItems.map(vi => {
-				const item = items![vi.index]
-				return (
-					<RowFrame
-						key={getKey(item, vi.index)}
-						index={vi.index}
-						count={count}
-						variant={variant}
-						hoverable={hoverable}
-						data-index={vi.index}
-						ref={virtualizer.measureElement}
-						className='absolute left-0 top-0 w-full'
-						style={{
-							transform: `translateY(${vi.start - virtualizer.options.scrollMargin}px)`,
-						}}
-					>
-						{renderItem(item, vi.index)}
-					</RowFrame>
-				)
-			})}
-		</div>,
-	)
-}
-
-// DataRow — каркас содержимого строки: слева медиа (пилюля/иконка) + колонка текста,
-// справа — трейлинг-слот (дата/бейдж). Сюда уезжает повторявшийся flex/justify/min-w-0.
-export function DataRow({
-	media,
-	end,
-	className,
-	children,
-}: {
-	/** Лидирующий элемент: пилюля суммы, иконка метода и т.п. */
-	media?: React.ReactNode
-	/** Трейлинг справа: дата, бейдж статуса. */
-	end?: React.ReactNode
-	className?: string
-	/** Текстовые строки (DataRowTitle/Subtitle/Caption). */
-	children?: React.ReactNode
-}) {
-	return (
-		<div
-			className={cn(
-				'flex items-center justify-between gap-fl-12/16',
-				className,
-			)}
-		>
-			<div className='flex min-w-0 items-center gap-fl-12/16'>
-				{media}
-				{children != null && (
-					<div className='flex min-w-0 flex-col gap-0.5'>{children}</div>
-				)}
-			</div>
-			{end}
-		</div>
-	)
-}
-
-// Текстовые линии строки — единая типографика, truncate против переполнения.
-export function DataRowTitle({
-	className,
-	...props
-}: React.ComponentProps<'span'>) {
-	return (
-		<span
-			className={cn(
-				'truncate text-body-m font-semibold text-foreground',
-				className,
-			)}
-			{...props}
-		/>
-	)
-}
-
-export function DataRowSubtitle({
-	className,
-	...props
-}: React.ComponentProps<'span'>) {
-	return (
-		<span
-			className={cn('truncate text-body-s text-muted-foreground', className)}
-			{...props}
-		/>
-	)
-}
-
-export function DataRowCaption({
-	className,
-	...props
-}: React.ComponentProps<'span'>) {
-	return (
-		<span
-			className={cn('truncate text-caption text-muted-foreground', className)}
-			{...props}
-		/>
-	)
-}
+'use client'
+
+import * as React from 'react'
+
+import { useWindowVirtualizer } from '@tanstack/react-virtual'
+
+import { Card } from '../card'
+import { Separator } from '../separator'
+import { useRevealOnce } from '../../hooks/useRevealOnce'
+import { cn } from '../../lib/utils'
+
+// data-list — примитив «разделённый список строк» (то, что в макете выглядит как
+// «таблица», но без шапки и колонок). Владеет общим каркасом: Card-оболочка,
+// вертикальные паддинги строк, разделители, скелетон-режим. Над списком — window-
+// виртуализация (@tanstack/react-virtual): на длинных списках в DOM живут только
+// видимые строки. Высота строк РАЗНАЯ (2–3 текст-линии) → меряем по факту
+// (measureElement). Стили — свои (у Radix примитива списка/таблицы нет, как и для
+// Card/Badge). Контент строки и его скелетон задаёт фича через renderItem/renderSkeleton.
+
+// useLayoutEffect на сервере шумит предупреждением → на SSR падаем в useEffect.
+const useIsoLayoutEffect =
+	typeof window !== 'undefined' ? React.useLayoutEffect : React.useEffect
+
+// Вариант каркаса списка:
+// - 'divided' (деф.) — один Card-конверт, строки разделены ui/Separator (то, что в макете
+//   выглядит как «таблица»);
+// - 'separated' — каждая строка отдельной Card с вертикальным зазором между ними (список
+//   карточек). Внешнего Card-конверта нет.
+export type DataListVariant = 'divided' | 'separated'
+
+// Каркас одной строки. Поведение зависит от variant.
+//
+// divided: Card-конверт без своего паддинга (p-0!) — все отступы задаёт строка:
+// - ui/Separator между строками (центрирован: mx-auto + 95% ширины);
+// - по бокам у всех px-fl-16/20; вертикаль между строками 11/15.
+//   Разделитель внутри строки → меряется вместе с ней (один код-путь для потока и
+//   виртуализации). hoverable → подсветка фона на наведение (full-bleed, Card без p).
+//
+// separated: строка = отдельная Card (свой паддинг/скругление). Зазор — pt у строк, кроме
+//   первой; паддинг ВХОДИТ в box → measureElement учитывает его и при виртуализации.
+//   hoverable → Card.interactive (курсор + подсветка рамки + лёгкое нажатие).
+//
+// ref как проп (React 19) — для measureElement виртуализатора.
+function RowFrame({
+	index,
+	// count в API строки оставлен (симметрия с index, нужен кастомным вариантам),
+	// но текущие варианты его не используют — вынимаем из ...props, чтобы не утёк в DOM.
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	count: _count,
+	variant = 'divided',
+	hoverable = false,
+	className,
+	children,
+	ref,
+	...props
+}: React.ComponentProps<'div'> & {
+	index: number
+	count: number
+	variant?: DataListVariant
+	hoverable?: boolean
+}) {
+	if (variant === 'separated') {
+		return (
+			<div
+				ref={ref}
+				className={cn(index > 0 && 'pt-fl-8/10', className)}
+				{...props}
+			>
+				<Card interactive={hoverable}>{children}</Card>
+			</div>
+		)
+	}
+
+	return (
+		<div ref={ref} className={className} {...props}>
+			{index > 0 && <Separator className='mx-auto w-[96%]!' />}
+			<div
+				className={cn(
+					'px-fl-16/20',
+					'py-fl-11/15',
+
+					hoverable && 'rounded-md transition-colors hover:bg-accent',
+				)}
+			>
+				{children}
+			</div>
+		</div>
+	)
+}
+
+export interface DataListProps<T> {
+	/** Данные. `undefined` = идёт загрузка → рисуем скелетон-строки. */
+	items: readonly T[] | undefined
+	/** Стабильный ключ строки. */
+	getKey: (item: T, index: number) => React.Key
+	/** Содержимое строки (обычно фичевый *-row компонент). */
+	renderItem: (item: T, index: number) => React.ReactNode
+	/** Содержимое скелетон-строки (тот же *-row без данных). */
+	renderSkeleton?: (index: number) => React.ReactNode
+	/** Сколько скелетон-строк показать при загрузке. */
+	skeletonCount?: number
+	/** Стартовая оценка высоты строки, px (дальше меряется по факту). */
+	estimateSize?: number
+	/** С какого размера списка включать виртуализацию. */
+	virtualizeThreshold?: number
+	/** Запас строк сверху/снизу видимой области. */
+	overscan?: number
+	/** Что показать, когда данные пришли, но список пуст. */
+	empty?: React.ReactNode
+	/** Подсветка строки на наведение (по умолчанию включена). */
+	hoverable?: boolean
+	/**
+	 * Вид списка: `divided` (деф.) — один Card с разделителями между строками;
+	 * `separated` — каждая строка отдельной Card с зазором между ними.
+	 */
+	variant?: DataListVariant
+	/**
+	 * Ключ одноразового каскада появления строк (reveal-stagger): первый показ за сессию —
+	 * строки всплывают лесенкой, повторный заход — список сразу. Без ключа каскада нет.
+	 * На виртуализированном списке каскад не играет (transform строк занят позиционированием).
+	 */
+	revealKey?: string
+	className?: string
+}
+
+export function DataList<T>({
+	items,
+	getKey,
+	renderItem,
+	renderSkeleton,
+	skeletonCount = 5,
+	estimateSize = 64,
+	virtualizeThreshold = 40,
+	overscan = 6,
+	empty,
+	hoverable = true,
+	variant = 'divided',
+	revealKey,
+	className,
+}: DataListProps<T>) {
+	const loading = items === undefined
+	const count = items?.length ?? 0
+	const shouldVirtualize = count > virtualizeThreshold
+	// Одноразовый каскад появления строк. Значение фиксируется на маунте: если компонент
+	// смонтировался в загрузке (скелетоны), каскад сыграет на приходе данных.
+	const revealPlay = useRevealOnce(revealKey)
+
+	// Внешний конверт списка: divided — единый Card (строки несут отступы сами, p-0!);
+	// separated — обычный блок, отступы и фон у каждой строки-Card. Это ФУНКЦИЯ-хелпер,
+	// а не компонент: вызываем как frame(...), иначе новый тип на каждый рендер ремаунтил
+	// бы всё поддерево (ломая виртуализацию/фокус).
+	const frame = (children: React.ReactNode) =>
+		variant === 'separated' ? (
+			<div className={cn('flex flex-col', className)}>{children}</div>
+		) : (
+			<Card className={cn('gap-0! p-0!', className)}>{children}</Card>
+		)
+
+	// Смещение списка от верха документа — scrollMargin для window-виртуализатора.
+	// Меряем после монтирования (и на resize); до этого виртуализация не активна.
+	const listRef = React.useRef<HTMLDivElement>(null)
+	const [scrollMargin, setScrollMargin] = React.useState(0)
+	useIsoLayoutEffect(() => {
+		if (!shouldVirtualize) return
+		const measure = () => {
+			if (listRef.current) {
+				setScrollMargin(
+					listRef.current.getBoundingClientRect().top + window.scrollY,
+				)
+			}
+		}
+		measure()
+		window.addEventListener('resize', measure)
+		return () => window.removeEventListener('resize', measure)
+	}, [shouldVirtualize])
+
+	// Хук вызываем всегда (правила хуков); при count=0 он по сути выключен.
+	const virtualizer = useWindowVirtualizer({
+		count: shouldVirtualize ? count : 0,
+		estimateSize: () => estimateSize,
+		overscan,
+		scrollMargin,
+	})
+
+	// — Загрузка: skeletonCount строк-заглушек (всегда в потоке, их мало).
+	if (loading) {
+		return frame(
+			Array.from({ length: skeletonCount }).map((_, i) => (
+				<RowFrame key={i} index={i} count={skeletonCount} variant={variant}>
+					{renderSkeleton?.(i)}
+				</RowFrame>
+			)),
+		)
+	}
+
+	// — Пусто.
+	if (count === 0) {
+		return empty ? frame(empty) : null
+	}
+
+	// — Короткий список: обычный поток, без оверхеда виртуализации. Каскад появления —
+	// только здесь (см. revealKey): reveal всплывает строку, задержка растёт до 10-й,
+	// дальше плато, чтобы длинный список не тянулся.
+	if (!shouldVirtualize) {
+		return frame(
+			items!.map((item, i) => (
+				<RowFrame
+					key={getKey(item, i)}
+					index={i}
+					count={count}
+					variant={variant}
+					hoverable={hoverable}
+					className={revealPlay ? 'reveal' : undefined}
+					style={
+						revealPlay
+							? { animationDelay: `${Math.min(i, 10) * 35}ms` }
+							: undefined
+					}
+				>
+					{renderItem(item, i)}
+				</RowFrame>
+			)),
+		)
+	}
+
+	// — Длинный список: window-виртуализация. В DOM только видимые строки, спейсер
+	// держит общую высоту, строки позиционируются translateY от измеренных позиций.
+	const virtualItems = virtualizer.getVirtualItems()
+	return frame(
+		<div
+			ref={listRef}
+			className='relative w-full'
+			style={{ height: virtualizer.getTotalSize() }}
+		>
+			{virtualItems.map(vi => {
+				const item = items![vi.index]
+				return (
+					<RowFrame
+						key={getKey(item, vi.index)}
+						index={vi.index}
+						count={count}
+						variant={variant}
+						hoverable={hoverable}
+						data-index={vi.index}
+						ref={virtualizer.measureElement}
+						className='absolute left-0 top-0 w-full'
+						style={{
+							transform: `translateY(${vi.start - virtualizer.options.scrollMargin}px)`,
+						}}
+					>
+						{renderItem(item, vi.index)}
+					</RowFrame>
+				)
+			})}
+		</div>,
+	)
+}
+
+// DataRow — каркас содержимого строки: слева медиа (пилюля/иконка) + колонка текста,
+// справа — трейлинг-слот (дата/бейдж). Сюда уезжает повторявшийся flex/justify/min-w-0.
+export function DataRow({
+	media,
+	end,
+	className,
+	children,
+}: {
+	/** Лидирующий элемент: пилюля суммы, иконка метода и т.п. */
+	media?: React.ReactNode
+	/** Трейлинг справа: дата, бейдж статуса. */
+	end?: React.ReactNode
+	className?: string
+	/** Текстовые строки (DataRowTitle/Subtitle/Caption). */
+	children?: React.ReactNode
+}) {
+	return (
+		<div
+			className={cn(
+				'flex items-center justify-between gap-fl-12/16',
+				className,
+			)}
+		>
+			<div className='flex min-w-0 items-center gap-fl-12/16'>
+				{media}
+				{children != null && (
+					<div className='flex min-w-0 flex-col gap-0.5'>{children}</div>
+				)}
+			</div>
+			{end}
+		</div>
+	)
+}
+
+// Текстовые линии строки — единая типографика, truncate против переполнения.
+export function DataRowTitle({
+	className,
+	...props
+}: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn(
+				'truncate text-body-m font-semibold text-foreground',
+				className,
+			)}
+			{...props}
+		/>
+	)
+}
+
+export function DataRowSubtitle({
+	className,
+	...props
+}: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn('truncate text-body-s text-muted-foreground', className)}
+			{...props}
+		/>
+	)
+}
+
+export function DataRowCaption({
+	className,
+	...props
+}: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn('truncate text-caption text-muted-foreground', className)}
+			{...props}
+		/>
+	)
+}