@cloud-ru/ds-list 1.0.0

package/src/components/Items/hooks.tsx

@@ -0,0 +1,233 @@
+import { useHierarchicalSelection } from '@cloud-ru/ds-utils';
+import { createRef, RefObject, useMemo } from 'react';
+
+import { ITEM_PREFIXES } from '../../constants';
+import { Separator } from '../../helperComponents';
+import { getFooterItemId } from '../../utils';
+import { useNewListContext, useSelectionContext } from '../Lists/contexts';
+import { AccordionItem } from './AccordionItem';
+import { BaseItem } from './BaseItem';
+import { GroupSelectItem } from './GroupSelectItem';
+import { NextListItem } from './NextListItem';
+import { SimpleGroupBlock, SimpleItem } from './SimpleItem';
+import {
+  Flatten,
+  FlattenAccordionItem,
+  FlattenBaseItem,
+  FlattenGroupSelectListItem,
+  FlattenItem,
+  FlattenNextListItem,
+  FlattenSimpleItem,
+  FocusFlattenItem,
+  ItemId,
+} from './types';
+import { isAccordionItem, isGroupItem, isGroupSelectItem, isNextListItem, isSimpleItem } from './utils';
+
+type GetRenderItemsProps = {
+  focusCloseChildIds?: ItemId[];
+  flattenItems: Record<string, FlattenItem>;
+  focusFlattenItems: Record<string, FocusFlattenItem>;
+  isSelectionMultiple?: boolean;
+  /**
+   * Id группы-родителя для строк режима переупорядочивания — передаётся в `data` `useSortable`
+   * (kind=row).
+   */
+  groupId?: ItemId;
+};
+
+function getRenderItems({
+  focusCloseChildIds,
+  focusFlattenItems,
+  flattenItems,
+  isSelectionMultiple,
+  groupId,
+}: GetRenderItemsProps): (JSX.Element | null)[] {
+  if (!focusCloseChildIds) {
+    return [null];
+  }
+
+  return focusCloseChildIds.flatMap(id => {
+    const { itemRef, key, originalId, items } = focusFlattenItems[id];
+
+    const flattenItem = flattenItems[originalId];
+
+    if (
+      isGroupItem(flattenItem) ||
+      (!isSelectionMultiple && isGroupSelectItem<FlattenGroupSelectListItem>(flattenItem))
+    ) {
+      // Группа в reorder-режиме: её строки размечены `type: Simple`. Заголовок + строки оборачиваются
+      // в единый сортируемый блок `SimpleGroupBlock` — за ручку заголовка группа перетаскивается
+      // целиком (строки едут вместе), а строки внутри блока переставляются собственным
+      // `SortableContext`. Переупорядочивание строго по уровням, см. `reorderReorderItems`.
+      const sortableChildIds = items
+        .map(focusId => focusFlattenItems[focusId]?.originalId)
+        .filter((childId): childId is ItemId => {
+          const child = childId != null ? flattenItems[childId] : undefined;
+          return Boolean(child && isSimpleItem(child));
+        });
+
+      const isSortableGroup = isGroupItem(flattenItem) && sortableChildIds.length > 0;
+
+      const innerItemsJSX = getRenderItems({
+        focusCloseChildIds: items,
+        focusFlattenItems,
+        flattenItems,
+        isSelectionMultiple,
+        groupId: isSortableGroup ? originalId : groupId,
+      });
+
+      if (isSortableGroup) {
+        return (
+          <SimpleGroupBlock
+            id={originalId}
+            label={flattenItem.label}
+            beforeContent={flattenItem.beforeContent}
+            truncate={flattenItem.truncate}
+            divider={flattenItem.divider}
+            groupVariant={flattenItem.groupVariant}
+            rowIds={sortableChildIds}
+            key={key}
+          >
+            {innerItemsJSX}
+          </SimpleGroupBlock>
+        );
+      }
+
+      return [
+        <Separator
+          label={flattenItem.label}
+          beforeContent={flattenItem.beforeContent}
+          truncate={flattenItem.truncate}
+          divider={flattenItem.divider}
+          groupVariant={flattenItem.groupVariant}
+          key={key + '_separator'}
+        />,
+        ...innerItemsJSX,
+      ];
+    }
+    if (isGroupSelectItem<FlattenGroupSelectListItem>(flattenItem)) {
+      return <GroupSelectItem {...flattenItem} items={items} itemRef={itemRef} key={key} />;
+    }
+    if (isAccordionItem<FlattenAccordionItem>(flattenItem)) {
+      return <AccordionItem {...flattenItem} items={items} itemRef={itemRef} key={key} />;
+    }
+    if (isNextListItem<FlattenNextListItem>(flattenItem)) {
+      return <NextListItem {...flattenItem} focusId={id} items={items} itemRef={itemRef} key={key} />;
+    }
+    if (isSimpleItem<FlattenSimpleItem>(flattenItem)) {
+      return <SimpleItem {...flattenItem} items={items} itemRef={itemRef} groupId={groupId} key={key} />;
+    }
+
+    return <BaseItem {...flattenItem} itemRef={itemRef} key={key} />;
+  });
+}
+
+export function useRenderItems(focusCloseChildIds?: ItemId[]) {
+  const { focusFlattenItems, flattenItems } = useNewListContext();
+  const { isSelectionMultiple } = useSelectionContext();
+
+  return useMemo(
+    () => getRenderItems({ flattenItems, focusFlattenItems, focusCloseChildIds, isSelectionMultiple }),
+    [flattenItems, focusCloseChildIds, focusFlattenItems, isSelectionMultiple],
+  );
+}
+
+type UseCreateBaseItemsProps = {
+  search?: boolean;
+  footerActiveElementsRefs?: RefObject<HTMLElement>[];
+};
+
+export function useCreateBaseItems({ footerActiveElementsRefs }: UseCreateBaseItemsProps): {
+  searchItem: Flatten<FlattenBaseItem, 'itemRef'>;
+  footerItems: Flatten<FlattenBaseItem, 'itemRef'>[];
+} {
+  return useMemo(
+    () => ({
+      searchItem: {
+        itemRef: createRef<HTMLInputElement>(),
+        id: ITEM_PREFIXES.search,
+        parentId: ITEM_PREFIXES.default,
+        items: [],
+        allChildIds: [],
+      },
+      footerItems:
+        footerActiveElementsRefs?.map((itemRef, idx) => ({
+          id: getFooterItemId(idx),
+          itemRef,
+          parentId: ITEM_PREFIXES.default,
+          items: [],
+          allChildIds: [],
+        })) ?? [],
+    }),
+    [footerActiveElementsRefs],
+  );
+}
+
+type UseGroupItemSelectionProps = {
+  allChildIds: ItemId[];
+  items: ItemId[];
+  id: ItemId;
+  disabled?: boolean;
+};
+
+export function useGroupItemSelection({ id, allChildIds }: UseGroupItemSelectionProps) {
+  const selection = useSelectionContext();
+  const { value, isSelectionMultiple } = selection;
+  const { getSelectionState, toggleSelection } = useHierarchicalSelection({ includeParentsInValue: false });
+  // group-select работает только в multiple-режиме — там setValue оперирует ItemId[].
+  const setMultipleValue = selection.isSelectionMultiple ? selection.setValue : undefined;
+  const { flattenItems } = useNewListContext();
+
+  const baseChildIds = useMemo(
+    () =>
+      allChildIds.filter(itemId => {
+        const item = flattenItems[itemId];
+
+        return item && !('type' in item);
+      }),
+    [allChildIds, flattenItems],
+  );
+
+  const enableChildIds = useMemo(
+    () =>
+      baseChildIds.filter(itemId => {
+        const item = flattenItems[itemId];
+
+        return item && !('type' in item) && !item.disabled;
+      }),
+    [baseChildIds, flattenItems],
+  );
+
+  const selectionState = useMemo(
+    () =>
+      isSelectionMultiple
+        ? getSelectionState({
+            nodeId: id,
+            childIds: baseChildIds,
+            selectedIds: value ?? [],
+          })
+        : undefined,
+    [baseChildIds, getSelectionState, id, isSelectionMultiple, value],
+  );
+
+  const checked = selectionState?.checked;
+  const indeterminate = isSelectionMultiple ? selectionState?.indeterminate : baseChildIds.includes(value ?? '');
+
+  const handleOnSelect = () => {
+    if (!isSelectionMultiple) {
+      return;
+    }
+
+    setMultipleValue?.(prev =>
+      toggleSelection({
+        nodeId: id,
+        descendantIds: baseChildIds,
+        selectableDescendantIds: enableChildIds,
+        childIds: baseChildIds,
+        selectedIds: prev ?? [],
+      }),
+    );
+  };
+
+  return { checked, indeterminate, handleOnSelect };
+}

package/src/components/Items/index.ts

@@ -0,0 +1,5 @@
+export * from './hooks';
+export * from './types';
+export * from './utils';
+export * from './SearchItem';
+export * from './PinGroupItem';

package/src/components/Items/styles.module.scss

@@ -0,0 +1,107 @@
+@use '@cloud-ru/ds-materials' as m;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/list.module' as list;
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+
+$sizes: 's', 'm', 'l';
+
+.stateLayer {
+  visibility: initial;
+}
+
+.itemWrapper {
+  position: relative;
+
+  // Локальный stacking context: запирает внутренние z-index'ы строки (state-layer, .listItem
+  // z-index:1, marker) внутри item'а, чтобы они не всплывали в контекст страницы поверх
+  // портальных overlay'ев.
+  z-index: 0;
+
+  min-width: 100%;
+  margin: 0;
+  padding: 0;
+
+  // Hover/pressed/focus через @cloud-ru/ds-materials state-layer (регулярный фон + активированный для selected single).
+  // data-state переключается в BaseItem.tsx: emptyNeutralOnBackground ↔ activatedOnBackground.
+  @include m.has-state-layer-as-child(#{stateLayer});
+
+  &[data-disabled],
+  &:disabled {
+    cursor: not-allowed;
+    background-color: transparent;
+    outline: none;
+  }
+
+  &:not([data-inactive], [data-disabled]) {
+    &[data-open],
+    &[data-focused] {
+      .stateLayer[data-state='emptyNeutralOnBackground'] {
+        background: base.$sn-theme-color-material-stateLayer-neutral-onBackground-hovered-filled;
+      }
+
+      .stateLayer[data-state='activatedOnBackground'] {
+        background: base.$sn-theme-color-material-stateLayer-activated-hovered-filled;
+      }
+    }
+
+    &:active {
+      .stateLayer[data-state='emptyNeutralOnBackground'] {
+        background: base.$sn-theme-color-material-stateLayer-neutral-onBackground-pressed-filled;
+      }
+
+      .stateLayer[data-state='activatedOnBackground'] {
+        background: base.$sn-theme-color-material-stateLayer-activated-pressed-filled;
+      }
+    }
+  }
+
+  // Миксин has-state-layer-as-child гасит hover/active state-layer только для
+  // data-disabled/data-loading. data-inactive — list-специфичный «неинтерактивный» флаг,
+  // миксин про него не знает → глушим state-layer и для него (перебиваем по специфичности).
+  &[data-inactive] {
+    &:hover,
+    &:active {
+      .stateLayer[data-state='emptyNeutralOnBackground'],
+      .stateLayer[data-state='activatedOnBackground'] {
+        background: base.$sn-theme-color-material-stateLayer-neutral-onBackground-defaultEmpty-filled;
+      }
+    }
+  }
+}
+
+.listItem {
+  cursor: pointer;
+
+  position: relative;
+
+  display: flex;
+  flex-direction: row;
+  align-items: flex-start;
+
+  box-sizing: border-box;
+  width: max-content;
+  min-width: 100%;
+  margin: 0;
+  padding: 0;
+  border: none;
+
+  color: base.$sn-theme-color-available-version-textMain;
+  text-align: start;
+
+  appearance: unset;
+  background-color: transparent;
+  outline: none;
+
+  @each $size in $sizes {
+    &[data-size='#{$size}'] {
+      @include base.composite-var(list.$list, 'anatomy', 'size', $size, 'listItem');
+    }
+  }
+
+  &:not([data-inactive], [data-disabled]) {
+    &[data-focused],
+    &:focus-visible {
+      outline: base.$sn-theme-color-available-complementary solid base.$sn-primitive-strokeWeight-strokeSemiBold;
+      outline-offset: calc(0px - base.$sn-primitive-strokeWeight-strokeSemiBold);
+    }
+  }
+}

package/src/components/Items/types.ts

@@ -0,0 +1,203 @@
+import { TruncateStringProps } from '@cloud-ru/ds-truncate-string';
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+import { FocusEvent, KeyboardEvent, MouseEvent, ReactNode, RefObject } from 'react';
+
+import { ITEM_TYPE } from '../../constants';
+import { ItemContentProps } from '../../helperComponents';
+import { ItemType, ScrollProps } from '../../types';
+
+/** Идентификатор элемента списка */
+export type ItemId = string | number;
+
+type ItemContent = ItemContentProps;
+
+export type BaseItem = WithSupportProps<{
+  /**
+   * Слот до основного контента
+   * @type ReactElement
+   */
+  beforeContent?: ReactNode;
+  /**
+   * Слот после основного контента
+   * @type ReactElement
+   */
+  afterContent?: ReactNode;
+  /**
+   * Основной контент айтема
+   */
+  content?: ItemContent | ReactNode;
+  /** Колбек обработки клика */
+  onClick?(e: MouseEvent<HTMLElement>): void;
+  /** Колбек обработки нажатия кнопки мыши */
+  onMouseDown?(e: MouseEvent<HTMLElement>): void;
+  /** Колбек обработки нажатия клавиши */
+  onKeyDown?(e: KeyboardEvent<HTMLElement>): void;
+  /** Колбек обработки фокуса */
+  onFocus?(e: FocusEvent<HTMLElement>): void;
+  /** Колбек обработки блюра */
+  onBlur?(e: FocusEvent<HTMLElement>): void;
+  /** Уникальный идентификатор */
+  id?: ItemId;
+  /** Флаг неактивности элемента */
+  disabled?: boolean;
+  /** Скрыть элемент из списка (не рендерится и выпадает из навигации) */
+  hidden?: boolean;
+  /** Ссылка на DOM-элемент айтема */
+  itemRef?: RefObject<HTMLElement>;
+  /** CSS-класс */
+  className?: string;
+  /**
+   * Флаг отображения отключения реакции на любое css состояние (hover/focus и тд)
+   * <br>
+   * Так же элемент пропадает из навигации с клавиатуры, и не может быть выбран (selection)
+   */
+  inactive?: boolean;
+  /**
+   * Флаг отображения состояния выбранного элемента через switch
+   */
+  switch?: boolean;
+  /**
+   * Флаг отображения иконки у чекбоксов
+   */
+  showSwitchIcon?: boolean;
+  /** Рендер-обёртка вокруг айтема (например, для проксирования в `Tooltip`/`Link`) */
+  itemWrapRender?(item: ReactNode): ReactNode;
+  /** Управляемое состояние выбранности айтема */
+  checked?: boolean;
+}>;
+
+type BaseItemWithoutNonGroup = Omit<BaseItem, 'switch' | 'inactive'>;
+
+export type Item = BaseItem | AccordionItem | NextListItem | GroupItem | GroupSelectItem;
+
+export type AccordionItem = BaseItemWithoutNonGroup & {
+  items: Item[];
+  type: typeof ITEM_TYPE.Collapse;
+};
+
+export type NextListItem = BaseItemWithoutNonGroup &
+  ScrollProps & {
+    items: Item[];
+    type: typeof ITEM_TYPE.NextList;
+
+    /** Колбек смены состояния вложенного списка (открыт/закрыт) */
+    onSublistOpenChanged?(open: boolean, id?: ItemId): void;
+
+    /** Состояние загрузки вложенного списка — показывается спиннер вместо элементов */
+    loading?: boolean;
+    /** Загрузка вложенного списка завершилась ошибкой — показывается `errorDataState` */
+    dataError?: boolean;
+    /** Вложенный список отфильтрован — пустой результат показывает `noResultsState`, а не `noDataState` */
+    dataFiltered?: boolean;
+
+    /** Сторона, с которой раскрывается вложенный список относительно элемента */
+    placement?: 'right-start' | 'left-start' | 'left' | 'right' | 'left-end' | 'right-end';
+  };
+
+type CommonGroupItem = {
+  /** Заголовок группы */
+  label?: string;
+  /** Слот иконки слева от label. */
+  beforeContent?: ReactNode;
+  /** Настройки усечения длинного заголовка группы */
+  truncate?: {
+    variant?: TruncateStringProps['variant'];
+  };
+  /** Визуальный стиль заголовка группы */
+  groupVariant?: 'subtitle' | 'subtitleTertiary';
+  /** Скрыть группу из списка */
+  hidden?: boolean;
+  /** Показать разделитель над группой */
+  divider?: boolean;
+};
+
+export type GroupItem = CommonGroupItem & {
+  items: Item[];
+  type: typeof ITEM_TYPE.Group;
+};
+
+export type GroupSelectItem = CommonGroupItem & {
+  items: Item[];
+  type: typeof ITEM_TYPE.GroupSelect;
+  selectButtonLabel?: string;
+
+  id?: ItemId;
+  itemRef?: RefObject<HTMLElement>;
+};
+
+type RequiredFields<T, K extends keyof T> = Required<Pick<T, K>> & Omit<T, K>;
+export type Flatten<T, K extends keyof T> = RequiredFields<T, K>;
+
+export type CommonFlattenProps = {
+  items: ItemId[];
+  allChildIds: ItemId[];
+};
+
+export type FlattenBaseItem = Flatten<BaseItem, 'id'>;
+export type FlattenNextListItem = Flatten<Omit<NextListItem, 'items'>, 'id'>;
+export type FlattenGroupListItem = Omit<GroupItem, 'items'> & { id: ItemId };
+export type FlattenGroupSelectListItem = Flatten<Omit<GroupSelectItem, 'items'>, 'id'>;
+export type FlattenAccordionItem = Flatten<Omit<AccordionItem, 'items'>, 'id'>;
+
+/**
+ * Строка `List`/`Droplist` в режиме drag&drop-переупорядочивания (проп `onItemsReorder`) —
+ * облегчённый аналог `BaseItem` без `type`-дискриминатора и без вложенности: не поддерживает
+ * `collapse`/`group-select`/`next-list`. `id` обязателен (нужен `@dnd-kit` как identity
+ * сортируемого элемента). Верхний уровень reorder-дерева описывает `ReorderItem` (строка или
+ * группа с заголовком); переупорядочивание идёт только среди «братьев» — строк одного уровня
+ * (внутри одной группы либо между строками без группы), перенос между группами не поддерживается,
+ * см. `reorderReorderItems`.
+ *
+ * `disabled` блокирует выбор, `Switch` и клик, но **не** ручку перетаскивания — порядок можно менять и у
+ * задизейбленных строк.
+ */
+export type SimpleItem = Flatten<BaseItem, 'id'>;
+
+/**
+ * Группа reorder-режима: заголовок (`label` и остальные поля `GroupItem`) + сортируемые строки
+ * `items`. Строки переставляются **внутри** группы, а сама группа переставляется среди других
+ * групп верхнего уровня (за ручку на заголовке) — поэтому у группы обязателен `id` (identity для
+ * `@dnd-kit`). Вложенность ограничена одним уровнем: в `items` только листовые `SimpleItem`.
+ */
+export type SimpleGroupItem = CommonGroupItem & {
+  /** Идентификатор группы — нужен `@dnd-kit` для переупорядочивания групп между собой. */
+  id: ItemId;
+  items: SimpleItem[];
+  type: typeof ITEM_TYPE.Group;
+};
+
+/** Верхнеуровневый элемент reorder-дерева (`onItemsReorder`): строка или группа с заголовком. */
+export type ReorderItem = SimpleItem | SimpleGroupItem;
+
+export type FlattenSimpleItem = FlattenBaseItem & CommonFlattenProps;
+
+export type FlattenItem =
+  | FlattenBaseItem
+  | ((
+      | FlattenNextListItem
+      | FlattenGroupListItem
+      | FlattenAccordionItem
+      | FlattenGroupSelectListItem
+      | FlattenSimpleItem
+    ) &
+      CommonFlattenProps);
+
+export type FocusFlattenItem = {
+  key: ItemId;
+  id: ItemId;
+
+  originalId: ItemId;
+  parentId?: ItemId;
+
+  itemRef?: RefObject<HTMLElement>;
+  type?: ItemType;
+
+  disabled?: boolean;
+} & CommonFlattenProps;
+
+export type ItemProps = Item;
+export type BaseItemProps = BaseItem;
+export type GroupItemProps = GroupItem;
+export type NextListItemProps = NextListItem;
+export type AccordionItemProps = AccordionItem;
+export type GroupSelectItemProps = GroupSelectItem;