@cloud-ru/ds-tooltip 1.0.0

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@cloud-ru/ds-tooltip",
+  "version": "1.0.0",
+  "description": "Пакет подсказок — компонент Tooltip для произвольного триггера и QuestionTooltip с иконкой «?» для полей форм и сложной терминологии.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloud-ru-tech/snack-v2.git",
+    "directory": "packages/tooltip"
+  },
+  "homepage": "https://github.com/cloud-ru-tech/snack-v2/tree/master/packages/tooltip",
+  "license": "Apache-2.0",
+  "author": "Anna Kozlova <apkozlova@cloud.ru>",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "./CHANGELOG.md",
+    "./LICENSE"
+  ],
+  "sideEffects": [
+    "*.css",
+    "**/*.css"
+  ],
+  "dependencies": {
+    "classnames": "^2.5.1",
+    "@cloud-ru/ds-icons": "^1.0.0",
+    "@cloud-ru/ds-utils": "^1.0.0",
+    "@cloud-ru/ds-popover-private": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/components/QuestionTooltip/QuestionTooltip.tsx

@@ -0,0 +1,59 @@
+import { QuestionSVG } from '@cloud-ru/ds-icons/interface/system';
+import { TRIGGER } from '@cloud-ru/ds-popover-private';
+import { useUncontrolledProp } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { RefObject } from 'react';
+
+import { SIZE, TEST_IDS } from '../../constants';
+import { getIconSize } from '../../utils';
+import { Tooltip } from '../Tooltip';
+import styles from './styles.module.scss';
+import { QuestionTooltipProps } from './types';
+
+/**
+ * QuestionTooltip — иконка «?» с тултипом-popover для подсказок к полям форм.
+ * Поверхность одна на всех раскладках (по договорённости с дизайном mobile не свапается на BottomSheet).
+ */
+export function QuestionTooltip({
+  tip,
+  triggerLabel = 'Подсказка',
+  trigger = TRIGGER.Hover,
+  className,
+  tooltipClassname,
+  open,
+  onOpenChange,
+  tabIndex = 0,
+  size = SIZE.XS,
+  triggerRef,
+  ...rest
+}: QuestionTooltipProps) {
+  const [isOpen, setIsOpen] = useUncontrolledProp(open, false, onOpenChange);
+
+  return (
+    <Tooltip
+      tip={tip}
+      className={tooltipClassname}
+      triggerClassName={styles.questionTooltipTrigger}
+      open={isOpen}
+      onOpenChange={setIsOpen}
+      trigger={trigger}
+      {...rest}
+    >
+      <button
+        type='button'
+        aria-label={triggerLabel}
+        data-opened={isOpen}
+        data-trigger={trigger}
+        tabIndex={tabIndex}
+        className={cn(styles.button, className)}
+        data-size={size}
+        data-test-id={TEST_IDS.questionTooltip.triggerOpen}
+        // Ref ведёт на саму кнопку, а не на span-обёртку popover'а: потребителю
+        // нужен настоящий триггер (позиционирование, фокус).
+        ref={triggerRef as RefObject<HTMLButtonElement>}
+      >
+        <QuestionSVG size={getIconSize(size)} />
+      </button>
+    </Tooltip>
+  );
+}

package/src/components/QuestionTooltip/index.ts

@@ -0,0 +1,2 @@
+export * from './QuestionTooltip';
+export * from './types';

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

@@ -0,0 +1,51 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+
+$sizes: 'xs', 's';
+
+.questionTooltipTrigger {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.button {
+  cursor: pointer;
+
+  position: relative;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+
+  margin: 0;
+  padding: 0;
+  border: none;
+
+  font: inherit;
+  color: base.$sn-theme-color-available-version-textTertiary;
+
+  background: transparent;
+
+  &:focus-visible {
+    outline: base.$sn-primitive-strokeWeight-strokeSemiBold solid base.$sn-theme-color-available-complementary;
+  }
+
+  &:active {
+    color: base.$sn-theme-color-available-version-textMain;
+  }
+
+  @media (hover: hover) {
+    // `:not(:active)` — иначе hover перебивает pressed и мышью он недостижим.
+    &:hover:not(:active) {
+      color: base.$sn-theme-color-available-version-textSecondary;
+    }
+  }
+
+  @each $size in $sizes {
+    &[data-size='#{$size}'] {
+      width: base.simple-var(base.$sn-density, 'size', 'icon', $size);
+      height: base.simple-var(base.$sn-density, 'size', 'icon', $size);
+    }
+  }
+}

package/src/components/QuestionTooltip/types.ts

@@ -0,0 +1,20 @@
+import { Size } from '../../types';
+import { TooltipProps } from '../Tooltip';
+
+/**
+ * QuestionTooltip: иконка «?» с тултипом-popover. Поверхность одна на всех раскладках.
+ * `tooltipClassname` применяется к контейнеру подсказки.
+ */
+export type QuestionTooltipProps = TooltipProps & {
+  /** CSS-класс контейнера подсказки */
+  tooltipClassname?: string;
+  /** Доступное имя для иконки-триггера */
+  triggerLabel?: string;
+  /** Tab index для кнопки-триггера */
+  tabIndex?: number;
+  /**
+   * Размер
+   * @default xs
+   */
+  size?: Size;
+};

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,69 @@
+import { PLACEMENT, PopoverPrivate, PopoverPrivateProps, TRIGGER } from '@cloud-ru/ds-popover-private';
+import { WithSupportProps } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { ReactNode } from 'react';
+
+import styles from './styles.module.scss';
+
+export type TooltipProps = WithSupportProps<{
+  /** Содержимое тултипа (текст или разметка) */
+  tip: ReactNode;
+  /** Отключение ограничения ширины тултипа @default false */
+  disableMaxWidth?: boolean;
+}> &
+  Pick<
+    PopoverPrivateProps,
+    | 'className'
+    | 'triggerClassName'
+    | 'offset'
+    | 'open'
+    | 'onOpenChange'
+    | 'hoverDelayOpen'
+    | 'hoverDelayClose'
+    | 'triggerRef'
+    | 'disableSpanWrapper'
+    | 'fallbackPlacements'
+    | 'closeOnPopstate'
+  > &
+  Partial<Pick<PopoverPrivateProps, 'trigger' | 'placement' | 'children'>>;
+
+export const DEFAULT_FALLBACK_PLACEMENTS = [PLACEMENT.Top, PLACEMENT.Right, PLACEMENT.Bottom, PLACEMENT.Left];
+
+/**
+ * Tooltip — всплывающая подсказка при наведении.
+ * Стили и анатомия (отступы, скругления, макс. ширина) из @cloud-ru/ds-figma-variables.
+ * DOM повторяет структуру из Figma: корневой контейнер и слои (фон, контейнер контента, указатель) с position: absolute.
+ */
+export function Tooltip({
+  children,
+  tip,
+  placement = PLACEMENT.Top,
+  trigger = TRIGGER.HoverAndFocusVisible,
+  hoverDelayOpen = 0,
+  hoverDelayClose = 0,
+  triggerClassName,
+  disableMaxWidth = false,
+  ...otherProps
+}: TooltipProps) {
+  return (
+    <PopoverPrivate
+      trigger={trigger}
+      placement={placement}
+      hasArrow
+      arrowContainerClassName={styles.pointerWrapper}
+      arrowElementClassName={styles.pointerShape}
+      hoverDelayOpen={hoverDelayOpen}
+      hoverDelayClose={hoverDelayClose}
+      fallbackPlacements={DEFAULT_FALLBACK_PLACEMENTS}
+      triggerClassName={cn(styles.triggerClassName, triggerClassName)}
+      popoverContent={
+        <div className={styles.tooltipContainer} data-disable-max-width={disableMaxWidth} role='tooltip'>
+          {tip}
+        </div>
+      }
+      {...otherProps}
+    >
+      {children}
+    </PopoverPrivate>
+  );
+}

package/src/components/Tooltip/index.ts

@@ -0,0 +1 @@
+export * from './Tooltip';

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

@@ -0,0 +1,41 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/tooltip.module' as tooltip;
+@use '@cloud-ru/ds-figma-variables/build/scss/components/popover.module' as popover;
+
+.triggerClassName {
+  --offset: #{base.simple-var(popover.$popover, 'anatomy', 'privatePopover', 'offset')};
+}
+
+.tooltipContainer {
+  @include base.composite-var(tooltip.$tooltip, 'anatomy', 'container');
+  @include base.composite-var(base.$base-styles, 'sn', 'regular', 'body', 's');
+
+  display: flex;
+  flex-direction: column;
+
+  box-sizing: border-box;
+
+  color: base.$sn-theme-color-available-inversion-textMain;
+  overflow-wrap: break-word;
+
+  background: base.$sn-theme-color-invertNeutral-background2Level;
+
+  &[data-disable-max-width='true'] {
+    max-width: calc(100vw - #{base.$sn-primitive-dimension-16});
+  }
+}
+
+// Отступ указателя от угла держит кламп floating-ui (`arrow({ padding })`), паддингом его дублировать нельзя.
+.pointerWrapper {
+  position: absolute;
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  color: base.$sn-theme-color-invertNeutral-background2Level;
+}
+
+.pointerShape {
+  fill: currentcolor;
+}

package/src/components/WithTooltip/WithTooltip.tsx

@@ -0,0 +1,16 @@
+import { Tooltip, TooltipProps } from '../Tooltip';
+
+type WithTooltipProps = {
+  /** Настройки для тултипа */
+  tooltip?: Omit<TooltipProps, 'children'>;
+  /** Триггер поповера (подробнее в TooltipProps) */
+  children: TooltipProps['children'];
+};
+
+export function WithTooltip({ tooltip, children }: WithTooltipProps) {
+  if (!tooltip?.tip) {
+    return <>{children}</>;
+  }
+
+  return <Tooltip {...tooltip}>{children}</Tooltip>;
+}

package/src/components/WithTooltip/index.ts

@@ -0,0 +1 @@
+export * from './WithTooltip';

package/src/components/index.ts

@@ -0,0 +1,3 @@
+export * from './QuestionTooltip';
+export * from './Tooltip';
+export * from './WithTooltip';

package/src/constants.ts

@@ -0,0 +1,11 @@
+export const SIZE = {
+  XS: 'xs',
+  S: 's',
+} as const;
+
+/** Стабильные `data-test-id` на внутренних слотах, которые компонент ставит сам. */
+export const TEST_IDS = {
+  questionTooltip: {
+    triggerOpen: 'question-tooltip-trigger',
+  },
+} as const;

package/src/index.ts

@@ -0,0 +1,5 @@
+export { TRIGGER, PLACEMENT } from '@cloud-ru/ds-popover-private';
+export * from './components';
+export type { Placement } from './types';
+export { SIZE } from './constants';
+export type { Size } from './types';

package/src/types.ts

@@ -0,0 +1,7 @@
+import { PLACEMENT } from '@cloud-ru/ds-popover-private';
+import { ValueOf } from '@cloud-ru/ds-utils';
+
+import { SIZE } from './constants';
+
+export type Placement = (typeof PLACEMENT)[keyof typeof PLACEMENT];
+export type Size = ValueOf<typeof SIZE>;

package/src/utils.ts

@@ -0,0 +1,14 @@
+import { SIZE } from './constants';
+import { Size } from './types';
+
+export function getIconSize(size?: Size) {
+  switch (size) {
+    case SIZE.XS: {
+      return 16;
+    }
+    case SIZE.S:
+    default: {
+      return 24;
+    }
+  }
+}