@snack-uikit/droplist

Droplist

Installation

npm i @snack-uikit/droplist

Changelog

Пакет экспортирует 4 компонента:

• Dropdown - компонент выпадающего контейнера общего назначения
• Droplist - компонент выпадащего вложенного меню
• ItemSingle - айтем списка меню с единичным выбором
• ItemMultiple - айтем списка меню с множественным выбором

Чтобы указать оффсет через стили надо в triggerClassName передать css-переменную --offset

Например:

.triggerClassName {
  --offset: #{$some-var};
}

Важное уточнение, если переменная передается через  scss-var она должна быть обернута в #{ }

Если значение явно передано через prop offset, то будет применено значение пропа.

Управление с клавиатуры

Для настройки управления/переключения между айметами и триггером с клавиатуры можно воспользоваться хуком Droplist.useKeyboardNavigation<T>({setDroplistOpen})

Пример использования:

  const MyComponent = () => {
    const [isOpen, setIsOpen] = useState(false);

    const {
      firstElementRefCallback,
      handleDroplistFocusLeave,
      handleTriggerKeyDown,
      handleDroplistItemKeyDown,
      triggerElementRef,
    } = Droplist.useKeyboardNavigation<HTMLButtonElement>({ setDroplistOpen: setIsOpen });

    const options =  Array.from({ length: 10 }).map((_, i) => ({
        option: `Option ${i + 1}`,
        onKeyDown: handleDroplistItemKeyDown, 
        onClick: () => {}
      }));


    return (
      <Droplist
        open={isOpen}
        onOpenChange={setIsOpen}
        firstElementRefCallback={firstElementRefCallback}
        onFocusLeave={handleDroplistFocusLeave}
        triggerElement={
          <button
            onKeyDown={handleTriggerKeyDown}
            ref={triggerElementRef}
          > 
            Click
          </button>
        }
      >
        {oprions.map(option => 
          <Droplist.ItemSingle {...option} />
        )}
      </Droplist>
    )
  }

Общие пропсы для ItemSingle и ItemMultiple

option: string

Заголовок айтема

caption?: string

Вторичный заголовок

description?: string

Описание айтема

tagLabel?: string

Текст тэга

size?: Size - s

Размер айтема, возможные значения:

• sizes.S
• sizes.M
• sizes.L

disabled?: boolean

Флаг, задизейблен ли айтем

icon?: ReactElement

Иконка (из пакета icons)

avatar?: Omit<AvatarProps, 'size'>

Пропсы для аватара (@nack-ui/avatar), исключая размер.

className?: string

CSS-класс контейнера

tabIndex?: number

Значение аттрибута tabIndex

checked: boolean

Флаг, выбран ли айтем

hasChecked: boolean

Флаг, есть ли в подменю выбранные айтемы. (подсвечивает айтем)

onChange: (checked: boolean): void

Колбэк выбора айтема

ItemMultiple

indeterminate?: boolean

Флаг неопределенного состояния (полувыбранный чекбокс)

Dropdown

Компонент Container использует под собой компонент PopoverPrivate (readme ниже);

content: ReactNode

содержимое дроплиста

open?: boolean - [undefined]

управляет состоянием показан/не показан.

onOpenChange?: (isOpen: boolean) => void - [undefined]

колбек отображения компонента. Срабатывает при изменении состояния open.

placement?: Placement - top

положение дроплиста относительно своего таргета (children). Возможные значения: Left, LeftStart, LeftEnd, Right, RightStart, RightEnd, Top, TopStart, TopEnd, Bottom, BottomStart, BottomEnd

trigger?: Trigger - click

триггер открытия/закрытия дроплиста.

• Click - открывать по клику
• Hover - открывать по ховеру
• FocusVisible - открывать по focus-visible
• Focus - открывать по фокусу
• HoverAndFocusVisible - открывать по ховеру и focus-visible
• HoverAndFocus - открывать по ховеру и фокусу
• ClickAndFocusVisible - открывать по клику и focus-visible

hoverDelayOpen?: number

задержка отображения при ховере в мс

hoverDelayClose?: number

задержка закрытия при ховере в мс

widthStrategy?: PopoverWidthStrategy

стратегия управления шириной контейнера дроплиста

• auto - соответствует ширине контента,
• gte - Great Then or Equal, равен ширине таргета или больше ее, если контент в дроплисте шире,
• eq - Equal, строго равен ширине таргета.

className?: string

CSS-класс на контейнере дроплиста.

triggerClassName?: string

CSS-класс на обёртке триггера поповера.

offset?: number

Отступ дроплиста от его target-элемента (в пикселях).

closeOnEscapeKey?: boolean - [true]

Закрывается ли поповер по нажатию клавиши Escape

triggerClickByKeys?: boolean - [true]

Вызывается ли попоповер по нажатию клавиш Enter/Space (при trigger = click)

Droplist

Повторяет пропсы компонента dropdown за исключением

triggerElement: ReactNode

триггер-элемент, относительно которого открывается Droplist

children: ReactNode

содержимое дроплиста

Droplist

Props

name	type	default value	description
triggerElement*	ReactNode | ChildrenFunction	-
className	string	-	CSS-класс
triggerClassName	string	-	CSS-класс триггера
open	boolean	-	Управляет состоянием показан/не показан.
onOpenChange	(isOpen: boolean) => void	-	Колбек отображения компонента. Срабатывает при изменении состояния open.
hoverDelayOpen	number	-	Задержка открытия по ховеру
hoverDelayClose	number	-	Задержка закрытия по ховеру
widthStrategy	enum PopoverWidthStrategy: "auto", "gte", "eq"	auto	Стратегия управления шириной контейнера поповера - auto - соответствует ширине контента, - gte - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, - eq - Equal, строго равен ширине таргета.
offset	number	0	Отступ поповера от его триггер-элемента (в пикселях).
closeOnEscapeKey	boolean	true	Закрывать ли по нажатию на кнопку Esc
triggerClickByKeys	boolean	true	Вызывается ли попоповер по нажатию клавиш Enter/Space (при trigger = click)
triggerRef	ForwardedRef<HTMLElement | ReferenceType>	-	Ref ссылка на триггер
outsideClick	boolean | OutsideClickHandler	-	Закрывать ли при клике вне поповера
fallbackPlacements	Placement[]	-	Цепочка расположений которая будет применяться к поповеру от первого к последнему если при текущем он не влезает.
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).
firstElementRefCallback	RefCallback<HTMLElement>	-
onFocusLeave	(direction: "left" | "top" | "bottom" | "common") => void	-
size	enum Size: "s", "m", "l"	-
scrollRef	RefObject<HTMLElement>	-
useScroll	boolean	-

Dropdown

Props

name	type	default value	description
children*	ReactNode | ChildrenFunction	-	Триггер поповера (подробнее читайте ниже)
content*	ReactNode	-
className	string	-	CSS-класс
triggerClassName	string	-	CSS-класс триггера
open	boolean	-	Управляет состоянием показан/не показан.
onOpenChange	(isOpen: boolean) => void	-	Колбек отображения компонента. Срабатывает при изменении состояния open.
hoverDelayOpen	number	-	Задержка открытия по ховеру
hoverDelayClose	number	-	Задержка закрытия по ховеру
widthStrategy	enum PopoverWidthStrategy: "auto", "gte", "eq"	gte	Стратегия управления шириной контейнера поповера - auto - соответствует ширине контента, - gte - Great Than or Equal, равен ширине таргета или больше ее, если контент в поповере шире, - eq - Equal, строго равен ширине таргета.
offset	number	0	Отступ поповера от его триггер-элемента (в пикселях).
closeOnEscapeKey	boolean	true	Закрывать ли по нажатию на кнопку Esc
triggerClickByKeys	boolean	true	Вызывается ли попоповер по нажатию клавиш Enter/Space (при trigger = click)
triggerRef	ForwardedRef<HTMLElement | ReferenceType>	-	Ref ссылка на триггер
outsideClick	boolean | OutsideClickHandler	-	Закрывать ли при клике вне поповера
fallbackPlacements	Placement[]	-	Цепочка расположений которая будет применяться к поповеру от первого к последнему если при текущем он не влезает.
trigger	enum Trigger: "click", "hover", "focusVisible", "focus", "hoverAndFocusVisible", "hoverAndFocus", "clickAndFocusVisible"	click	Условие отображения поповера: - 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"	bottom-start	Положение поповера относительно своего триггера (children).