1.0.1 • Published 2 weeks ago

@snack-uikit/list

Licence

Apache-2.0

Version

1.0.1

Deps

Size

493 kB

Vulns

Weekly

Stars

Summary Dependency Versions

List

Installation

npm i @snack-uikit/list

Changelog

Description

Пакет @snack-uikit/list предоставляет компоненты для отображения структурированных списков с поддержкой выбора элементов, поиска, группировки и вложенных структур.
Компоненты поддерживают различные типы элементов: базовые элементы, группы, аккордеоны и вложенные списки, а также режимы выбора (одиночный, множественный, без выбора).
Списки поддерживают закрепление элементов сверху и снизу, кастомный футер, поисковую строку, виртуализацию для больших объёмов данных и полноценную навигацию с клавиатуры.
Компоненты работают в контролируемом и неконтролируемом режимах, поддерживают состояния загрузки и пустых данных, а также настраиваемые экраны для различных сценариев (нет данных, нет результатов поиска, ошибка).

List

Description

List — компонент для отображения структурированного списка элементов, встраиваемого непосредственно в контент страницы.
Поддерживает режимы выбора элементов: одиночный (selection.mode="single"), множественный (selection.mode="multiple") и без выбора (selection не передан).
Позволяет закреплять элементы сверху (pinTop) и снизу (pinBottom), которые остаются видимыми при прокрутке основного списка.
Включает поисковую строку (search) для фильтрации элементов по содержимому.
Поддерживает различные типы элементов: базовые элементы, группы с заголовками, аккордеоны с раскрывающимся контентом и вложенные списки (next-list).
Может отображать кастомный футер (footer) с дополнительными элементами управления.
Поддерживает виртуализацию (virtualized) для оптимизации рендеринга больших списков (от 1000 элементов).
Обеспечивает навигацию с клавиатуры с поддержкой стрелок, Enter, Space и других клавиш для перемещения и выбора элементов.
Позволяет настраивать состояния пустых данных (noDataState, noResultsState, errorDataState) для различных сценариев.
Figma: List.

Example

import { List } from '@snack-uikit/list';

function Example() {
  const [selected, setSelected] = useState<string | undefined>();

  return (
    <List
      items={[
        {
          id: '1',
          content: { option: 'Первый элемент', description: 'Описание первого элемента' },
        },
        {
          id: '2',
          content: { option: 'Второй элемент', description: 'Описание второго элемента' },
        },
      ]}
      selection={{
        mode: 'single',
        value: selected,
        onChange: setSelected,
      }}
      search={{
        value: '',
        onChange: (value) => console.log('Search:', value),
        placeholder: 'Поиск...',
      }}
      pinTop={[
        {
          id: 'pinned-top',
          content: { option: 'Закреплённый элемент сверху' },
        },
      ]}
      footer={<button>Дополнительное действие</button>}
    />
  );
}

Droplist

Description

Droplist — компонент выпадающего списка, который отображается в поповере при взаимодействии с триггером (кнопкой, ссылкой или другим элементом).
Объединяет функциональность List с возможностями выпадающего меню: появляется по клику, ховеру, фокусу или другим триггерам и автоматически позиционируется относительно элемента-триггера.
Поддерживает различные триггеры открытия (trigger): click, hover, focus, focusVisible и их комбинации.
Позволяет настраивать позиционирование (placement) относительно триггера: сверху, снизу, слева, справа и их вариации.
Может автоматически закрываться после выбора элемента (closeDroplistOnItemClick) в режимах без выбора или одиночного выбора.
Поддерживает управление шириной поповера (widthStrategy): автоматическая, равная триггеру или больше триггера.
Включает все возможности List: выбор элементов, поиск, группировка, закрепление элементов, виртуализация и навигация с клавиатуры.
Триггер может быть передан как React-элемент или функция-рендер, которая получает обработчик onKeyDown для поддержки навигации с клавиатуры.
Figma: Droplist.

Example

import { Droplist } from '@snack-uikit/list';
import { ButtonFilled } from '@snack-uikit/button';

function Example() {
  const [selected, setSelected] = useState<string | undefined>();

  return (
    <Droplist
      items={[
        {
          id: '1',
          content: { option: 'Первый элемент', description: 'Описание первого элемента' },
        },
        {
          id: '2',
          content: { option: 'Второй элемент', description: 'Описание второго элемента' },
        },
      ]}
      selection={{
        mode: 'single',
        value: selected,
        onChange: setSelected,
      }}
      trigger="click"
      placement="bottom-start"
      closeDroplistOnItemClick
    >
      <ButtonFilled label="Выбрать элемент" />
    </Droplist>
  );
}

kindFlattenItems

Props

name	type	default value
items*	`Item[]`	-
prefix	`ItemId`	-
parentId	`ItemId`	-

isAccordionItem

Props

name	type	default value	description

isBaseItem

Props

name	type	default value	description

isGroupItem

Props

name	type	default value	description

isNextListItem

Props

name	type	default value	description

isGroupSelectItem

Props

name	type	default value	description

useGroupItemSelection

Props

name	type	default value
id*	`ItemId`	-
items*	`ItemId[]`	-
allChildIds*	`ItemId[]`	-
disabled	`boolean`	-

isSelectionSingleProps

Props

name	type	default value	description

isSelectionMultipleProps

Props

name	type	default value	description

Droplist

Props

name	type	default value	description
items*	`Item[]`	-	Основные элементы списка
children*	`ReactNode \| ({onKeyDown}) => ReactNode * Рендер функция принимает аргументы` onKeyDown `- хендлер ввода, для поддержки управления с клавиатуры`	-	Триггер для дроплиста
triggerElemRef	`RefObject<HTMLElement>`	-	Ссылка на элемент-триггер для дроплиста
listRef	`RefObject<HTMLElement>`	-	Ссылка на элемент выпадающего списка
closeDroplistOnItemClick	`boolean`	-	Закрывать выпадающий список после клика на базовый айтем. Работает в режимах selection: 'none' \| 'single'
virtualized	`boolean`	-	Включить виртуализацию на компоненты списка. Рекомендуется если у вас от 1к элементов списка
triggerClassName	`string`	-	CSS-класс триггера
open	`boolean`	-	Управляет состоянием показан/не показан.
onOpenChange	`(isOpen: boolean) => void`	-	Колбек отображения компонента. Срабатывает при изменении состояния open.
widthStrategy	enum PopoverWidthStrategy: `"auto"`, `"gte"`, `"eq"`	auto	Стратегия управления шириной контейнера поповера - `auto` - соответствует ширине контента, - `gte` - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, - `eq` - Equal, строго равен ширине таргета.
closeOnPopstate	`boolean`	-	Закрывать ли поповер при пекреходе по истории браузера
trigger	enum Trigger: `"click"`, `"hover"`, `"focusVisible"`, `"focus"`, `"hoverAndFocusVisible"`, `"hoverAndFocus"`, `"clickAndFocusVisible"`	-	Условие отображения поповера: - `click` - открывать по клику - `hover` - открывать по ховеру - `focusVisible` - открывать по focus-visible - `focus` - открывать по фокусу - `hoverAndFocusVisible` - открывать по ховеру и focus-visible - `hoverAndFocus` - открывать по ховеру и фокусу - `clickAndFocusVisible` - открывать по клику и focus-visible
placement	enum Placement: `"left"`, `"left-start"`, `"left-end"`, `"right"`, `"right-start"`, `"right-end"`, `"top"`, `"top-start"`, `"top-end"`, `"bottom"`, `"bottom-start"`, `"bottom-end"`	top	Положение поповера относительно своего триггера (children).
className	`string`	-	CSS-класс
pinTop	`Item[]`	-	Элементы списка, закрепленные сверху
pinBottom	`Item[]`	-	Элементы списка, закрепленные снизу
footer	`ReactNode ;`	-	Кастомизируемый элемент в конце списка
footerActiveElementsRefs	`RefObject<HTMLElement>[]`	-	Список ссылок на кастомные элементы, помещенные в специальную секцию внизу списка
search	`SearchState`	-	Настройки поисковой строки
collapse	`CollapseState`	{}	Настройки раскрытия элементов
loading	`boolean`	-	Флаг, отвещающий за состояние загрузки списка
scrollToSelectedItem	`boolean`	-	Флаг, отвещающий за прокручивание до выбранного элемента
scrollContainerClassName	`string`	-	CSS-класс для scroll обертки основного списка айтемов
selection	`SelectionSingleState \| SelectionMultipleState`	-
size	"s" \| "m" \| "l"	s	Размер списка
marker	`boolean`	true	Отображать ли маркер у выбранного жлемента списка
contentRender	`(props: ContentRenderProps) => ReactNode`	-	Рендер функция основного контента айтема
scroll	`boolean`	-	Включить ли скролл для основной части списка
scrollRef	`Ref<HTMLElement>`	-	Ссылка на элемент, обозначающий самый конец прокручиваемого списка
scrollContainerRef	`Ref<HTMLElement>`	-	Ссылка на контейнер, который скроллится
untouchableScrollbars	`boolean`	-	Отключает возможность взаимодействовать со скролбарами мышью.
barHideStrategy	enum BarHideStrategy: `"scroll"`, `"move"`, `"never"`, `"leave"`	-	Управление скрытием скролл баров: - `Never` - показывать всегда - `Leave` - скрывать когда курсор покидает компонент - `Scroll` - показывать только когда происходит скроллинг - `Move` - показывать при движении курсора над компонентом
onScroll	`(event?: Event) => void`	-	Колбек на скролл прокручиваемого списка
dataFiltered	`boolean`	-
dataError	`boolean`	-
noDataState	`EmptyStateProps`	-	Экран при отстутствии данных
noResultsState	`EmptyStateProps`	-	Экран при отстутствии результатов поиска или фильтров
errorDataState	`EmptyStateProps`	-	Экран при ошибке запроса

List

Props

name	type	default value	description
items*	`Item[]`	-	Основные элементы списка
pinTop	`Item[]`	-	Элементы списка, закрепленные сверху
pinBottom	`Item[]`	-	Элементы списка, закрепленные снизу
footer	`ReactNode ;`	-	Кастомизируемый элемент в конце списка
footerActiveElementsRefs	`RefObject<HTMLElement>[]`	-	Список ссылок на кастомные элементы, помещенные в специальную секцию внизу списка
keyboardNavigationRef	`RefObject<{ focusItem(id: ItemId): void; }>`	-	Ссылка на управление навигацией листа с клавиатуры
search	`SearchState`	-	Настройки поисковой строки
tabIndex	`number`	-	Tab Index
collapse	`CollapseState`	{}	Настройки раскрытия элементов
className	`string`	-	CSS-класс
loading	`boolean`	-	Флаг, отвещающий за состояние загрузки списка
onKeyDown	`(e: KeyboardEvent<HTMLElement>) => void`	-	Обработчик события по нажатию клавиш
hasListInFocusChain	`boolean`	true	Флаг, отвещающий за включение самого родительского контейнера листа в цепочку фокусирующихся элементов
scrollToSelectedItem	`boolean`	-	Флаг, отвещающий за прокручивание до выбранного элемента
scrollContainerClassName	`string`	-	CSS-класс для scroll обертки основного списка айтемов
virtualized	`boolean`	-	Включить виртуализацию на компоненты списка. Рекомендуется если у вас от 1к элементов списка
selection	`SelectionSingleState \| SelectionMultipleState`	-
size	"s" \| "m" \| "l"	s	Размер списка
marker	`boolean`	true	Отображать ли маркер у выбранного жлемента списка
contentRender	`(props: ContentRenderProps) => ReactNode`	-	Рендер функция основного контента айтема
scroll	`boolean`	-	Включить ли скролл для основной части списка
scrollRef	`Ref<HTMLElement>`	-	Ссылка на элемент, обозначающий самый конец прокручиваемого списка
scrollContainerRef	`Ref<HTMLElement>`	-	Ссылка на контейнер, который скроллится
untouchableScrollbars	`boolean`	-	Отключает возможность взаимодействовать со скролбарами мышью.
barHideStrategy	enum BarHideStrategy: `"scroll"`, `"move"`, `"never"`, `"leave"`	-	Управление скрытием скролл баров: - `Never` - показывать всегда - `Leave` - скрывать когда курсор покидает компонент - `Scroll` - показывать только когда происходит скроллинг - `Move` - показывать при движении курсора над компонентом
onScroll	`(event?: Event) => void`	-	Колбек на скролл прокручиваемого списка
dataFiltered	`boolean`	-
dataError	`boolean`	-
noDataState	`EmptyStateProps`	-	Экран при отстутствии данных
noResultsState	`EmptyStateProps`	-	Экран при отстутствии результатов поиска или фильтров
errorDataState	`EmptyStateProps`	-	Экран при ошибке запроса
ref	`LegacyRef<HTMLElement>`	-	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}
key	`Key`	-

ItemContent

Props

name	type	default value	description
option*	`string \| number`	-
caption	`string`	-
description	`string`	-
truncate	`TruncateProps`	-
disabled	`boolean`	-
className	`string`	-	CSS-класс

getFooterItemId

helper

Возвращает id для элемента футера

getItemAutoId

helper

Возвращает id для элемента, подставляя перфикс

getDefaultItemId

helper

Возвращает id для дефолтного элемента