@cloud-ru/ds-ai-suggestion 1.0.0

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@cloud-ru/ds-ai-suggestion",
+  "version": "1.0.0",
+  "description": "AI-подсказки — простой чип и раскрывающаяся группа с вложенными подсказками.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cloud-ru-tech/snack-v2.git",
+    "directory": "packages/ai-suggestion"
+  },
+  "homepage": "https://github.com/cloud-ru-tech/snack-v2/tree/master/packages/ai-suggestion",
+  "license": "Apache-2.0",
+  "author": "Артем Сауляк <avsaulyak@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",
+    "framer-motion": "^12.42.2",
+    "@cloud-ru/ds-icons": "^1.0.0",
+    "@cloud-ru/ds-utils": "^1.0.0",
+    "@cloud-ru/ds-materials": "^1.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/AiSuggestionParent/AiSuggestionParent.tsx

@@ -0,0 +1,257 @@
+import { extractSupportProps, useUncontrolledProp } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { MouseEvent, ReactNode, useCallback, useEffect, useState } from 'react';
+
+import { AiSuggestionSimple } from '../AiSuggestionSimple';
+import { APPEARANCE, SIZE } from '../AiSuggestionSimple/constants';
+import { Size } from '../AiSuggestionSimple/types';
+import { AiSuggestionParentChip } from './AiSuggestionParentChip';
+import { AnimatedExpandableItem, AnimatedTriggerWrap } from './animation/AnimatedExpandableItem';
+import { TEST_IDS } from './constants';
+import { AiSuggestionParentGroupProvider, useAiSuggestionParentGroup } from './context/AiSuggestionParentGroupContext';
+import styles from './styles.module.scss';
+import {
+  AiSuggestionParentItem,
+  AiSuggestionParentNestedItem,
+  AiSuggestionParentProps,
+  AiSuggestionParentSuggestionItem,
+} from './types';
+import { hasExclusiveParentGroup } from './utils/hasExclusiveParentGroup';
+import { isNestedItem, isSuggestionItem } from './utils/itemGuards';
+
+type AiSuggestionParentInternalProps = AiSuggestionParentProps & {
+  /** Родительская группа раскрыта — управляет видимостью вложенной ветки */
+  shown?: boolean;
+};
+
+type NestedAiSuggestionParentProps = {
+  index: number;
+  total: number;
+  shown: boolean;
+  node: AiSuggestionParentNestedItem;
+  size: NonNullable<AiSuggestionParentProps['size']>;
+  groupKey?: string;
+  onItemClick?: AiSuggestionParentProps['onItemClick'];
+};
+
+type RenderSuggestionLeafProps = {
+  item: AiSuggestionParentSuggestionItem;
+  index: number;
+  total: number;
+  shown: boolean;
+  size: Size;
+  onLeafClick?(event: MouseEvent<HTMLButtonElement>): void;
+};
+
+function renderSuggestionLeaf({ item, index, total, shown, size, onLeafClick }: RenderSuggestionLeafProps) {
+  const key = item.key ?? String(index);
+
+  return (
+    <AnimatedExpandableItem key={key} index={index} total={total} shown={shown}>
+      <AiSuggestionSimple
+        label={item.label}
+        icon={item.icon}
+        size={size}
+        disabled={item.disabled}
+        appearance={APPEARANCE.Primary}
+        tabIndex={shown ? 0 : -1}
+        onClick={(event: MouseEvent<HTMLButtonElement>) => {
+          event.stopPropagation();
+          item.onClick?.(event);
+          onLeafClick?.(event);
+        }}
+      />
+    </AnimatedExpandableItem>
+  );
+}
+
+function useNestedExpandedState(groupKey: string | undefined, shown: boolean) {
+  const group = useAiSuggestionParentGroup();
+  const isGroupControlled = group !== null && groupKey !== undefined;
+  const [localExpanded, setLocalExpanded] = useState(false);
+  const expanded = isGroupControlled ? group.expandedKey === groupKey : localExpanded;
+
+  useEffect(() => {
+    if (!shown) {
+      if (isGroupControlled && groupKey) {
+        group.collapseKey(groupKey);
+      } else {
+        setLocalExpanded(false);
+      }
+    }
+  }, [group, groupKey, isGroupControlled, shown]);
+
+  const handleExpandedChange = useCallback(
+    (next: boolean) => {
+      if (isGroupControlled && groupKey) {
+        group.requestExpand(groupKey);
+        return;
+      }
+
+      setLocalExpanded(next);
+    },
+    [group, groupKey, isGroupControlled],
+  );
+
+  return { expanded, handleExpandedChange };
+}
+
+function NestedAiSuggestionParent({
+  index,
+  total,
+  shown,
+  node,
+  size,
+  groupKey,
+  onItemClick,
+}: NestedAiSuggestionParentProps) {
+  const { expanded, handleExpandedChange } = useNestedExpandedState(groupKey, shown);
+  const childShown = shown && expanded;
+  const items = node.items ?? [];
+  const nestedChildren = items.filter(isNestedItem);
+  const leaves = items.filter(isSuggestionItem);
+  const hasExclusiveGroup = hasExclusiveParentGroup(items);
+
+  const nestedContent = (
+    <>
+      {nestedChildren.map((child, childIndex) => {
+        const childKey = child.key ?? `${node.label}-${child.label ?? childIndex}`;
+
+        return (
+          <NestedAiSuggestionParent
+            key={childKey}
+            index={childIndex}
+            total={nestedChildren.length}
+            shown={childShown}
+            node={child}
+            size={size}
+            groupKey={hasExclusiveGroup ? childKey : undefined}
+            onItemClick={onItemClick}
+          />
+        );
+      })}
+      {leaves.map((leaf, leafIndex) =>
+        renderSuggestionLeaf({
+          item: leaf,
+          index: leafIndex,
+          total: leaves.length,
+          shown: childShown,
+          size,
+        }),
+      )}
+    </>
+  );
+
+  return (
+    <>
+      <AnimatedExpandableItem index={index} total={total} shown={shown}>
+        <AiSuggestionParentChip
+          label={node.label}
+          icon={node.icon}
+          size={size}
+          disabled={node.disabled}
+          expanded={expanded}
+          onExpandedChange={handleExpandedChange}
+          tabIndex={shown ? 0 : -1}
+        />
+      </AnimatedExpandableItem>
+      {hasExclusiveGroup ? (
+        <AiSuggestionParentGroupProvider>{nestedContent}</AiSuggestionParentGroupProvider>
+      ) : (
+        nestedContent
+      )}
+    </>
+  );
+}
+
+function wrapExclusiveItems(items: AiSuggestionParentItem[], content: ReactNode) {
+  return hasExclusiveParentGroup(items) ? (
+    <AiSuggestionParentGroupProvider>{content}</AiSuggestionParentGroupProvider>
+  ) : (
+    content
+  );
+}
+
+export function AiSuggestionParent({
+  label = 'Label text',
+  icon,
+  size = SIZE.S,
+  disabled = false,
+  expanded: expandedProp,
+  defaultExpanded = false,
+  onExpandedChange,
+  items = [],
+  onItemClick,
+  className,
+  shown: shownProp = true,
+  ...rest
+}: AiSuggestionParentInternalProps) {
+  const [expanded, setExpanded] = useUncontrolledProp(expandedProp, defaultExpanded, onExpandedChange);
+  const shown = shownProp;
+  const childShown = shown && expanded;
+  const totalItems = items.length;
+  const hasExclusiveGroup = hasExclusiveParentGroup(items);
+  const rootTestId = rest['data-test-id'] ?? TEST_IDS.root;
+
+  useEffect(() => {
+    if (!shown && expanded) {
+      setExpanded(false);
+    }
+  }, [shown, expanded, setExpanded]);
+
+  const handleExpandedChange = useCallback(
+    (next: boolean) => {
+      if (disabled) {
+        return;
+      }
+
+      setExpanded(next);
+    },
+    [disabled, setExpanded],
+  );
+
+  const renderItem = (item: AiSuggestionParentItem, index: number) => {
+    if (isNestedItem(item)) {
+      const key = item.key ?? String(index);
+
+      return (
+        <NestedAiSuggestionParent
+          key={key}
+          index={index}
+          total={totalItems}
+          shown={childShown}
+          node={item}
+          size={size}
+          groupKey={hasExclusiveGroup ? key : undefined}
+          onItemClick={onItemClick}
+        />
+      );
+    }
+
+    return renderSuggestionLeaf({
+      item,
+      index,
+      total: totalItems,
+      shown: childShown,
+      size,
+      onLeafClick: event => onItemClick?.(index, event),
+    });
+  };
+
+  return (
+    <div className={cn(styles.root, className)} {...extractSupportProps(rest)} data-flatten data-test-id={rootTestId}>
+      <AnimatedTriggerWrap>
+        <AiSuggestionParentChip
+          label={label}
+          icon={icon}
+          size={size}
+          disabled={disabled}
+          expanded={expanded}
+          onExpandedChange={handleExpandedChange}
+          tabIndex={shown ? undefined : -1}
+        />
+      </AnimatedTriggerWrap>
+      {wrapExclusiveItems(items, items.map(renderItem))}
+    </div>
+  );
+}

package/src/AiSuggestionParent/AiSuggestionParentChip.tsx

@@ -0,0 +1,79 @@
+import { ChevronRightSVG } from '@cloud-ru/ds-icons/interface/system';
+import { extractSupportProps } from '@cloud-ru/ds-utils';
+import cn from 'classnames';
+import { ButtonHTMLAttributes, forwardRef, MouseEvent, ReactNode } from 'react';
+
+import { SIZE } from '../AiSuggestionSimple/constants';
+import { Size } from '../AiSuggestionSimple/types';
+import { TEST_IDS } from './constants';
+import styles from './styles.module.scss';
+
+export type AiSuggestionParentChipProps = {
+  label?: string;
+  icon?: ReactNode;
+  size?: Size;
+  disabled?: boolean;
+  expanded?: boolean;
+  onExpandedChange?(expanded: boolean): void;
+  chevron?: ReactNode;
+  className?: string;
+} & Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> & {
+    onClick?: (event: MouseEvent<HTMLButtonElement>) => void;
+  };
+
+export const AiSuggestionParentChip = forwardRef<HTMLButtonElement, AiSuggestionParentChipProps>(
+  function AiSuggestionParentChip(
+    {
+      label = 'Label text',
+      icon,
+      size = SIZE.S,
+      disabled = false,
+      expanded = false,
+      onExpandedChange,
+      chevron,
+      className,
+      type = 'button',
+      onClick,
+      ...rest
+    },
+    ref,
+  ) {
+    const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+      onClick?.(event);
+      if (event.defaultPrevented || disabled) {
+        return;
+      }
+
+      onExpandedChange?.(!expanded);
+    };
+
+    return (
+      <button
+        ref={ref}
+        type={type}
+        className={cn(styles.chip, className)}
+        {...extractSupportProps(rest)}
+        data-size={size}
+        data-activated={expanded || undefined}
+        data-test-id={TEST_IDS.trigger}
+        disabled={disabled}
+        aria-expanded={expanded}
+        onClick={handleClick}
+      >
+        {icon !== undefined && (
+          <span className={styles.icon} aria-hidden>
+            {icon}
+          </span>
+        )}
+        {label !== undefined && (
+          <span className={styles.labelContainer}>
+            <span className={styles.label}>{label}</span>
+          </span>
+        )}
+        <span className={styles.chevron} data-test-id={TEST_IDS.chevron} aria-hidden>
+          {chevron ?? <ChevronRightSVG className={styles.chevronIcon} size={24} />}
+        </span>
+      </button>
+    );
+  },
+);

package/src/AiSuggestionParent/animation/AnimatedExpandableItem.tsx

@@ -0,0 +1,53 @@
+import cn from 'classnames';
+import { motion } from 'framer-motion';
+import { ReactNode } from 'react';
+
+import { GAP_PX, innerChipTransition, layoutSpring, outerChipTransition } from './constants';
+import styles from './styles.module.scss';
+
+export type AnimatedExpandableItemProps = {
+  index: number;
+  total: number;
+  shown: boolean;
+  children: ReactNode;
+};
+
+export function AnimatedExpandableItem({ index, total, shown, children }: AnimatedExpandableItemProps) {
+  return (
+    <motion.div
+      layout='position'
+      initial={false}
+      animate={{
+        width: shown ? 'auto' : 0,
+        marginRight: shown ? GAP_PX : 0,
+      }}
+      transition={outerChipTransition(shown)}
+      className={styles.outerChip}
+      aria-hidden={!shown}
+    >
+      <motion.div
+        initial={false}
+        animate={{
+          scale: shown ? 1 : 0,
+          opacity: shown ? 1 : 0,
+        }}
+        transition={innerChipTransition(index, total, shown)}
+        className={cn(styles.innerChip, { [styles.innerChipHidden]: !shown })}
+      >
+        {children}
+      </motion.div>
+    </motion.div>
+  );
+}
+
+export type AnimatedTriggerWrapProps = {
+  children: ReactNode;
+};
+
+export function AnimatedTriggerWrap({ children }: AnimatedTriggerWrapProps) {
+  return (
+    <motion.div layout='position' transition={{ layout: layoutSpring }} className={styles.triggerWrap}>
+      {children}
+    </motion.div>
+  );
+}

package/src/AiSuggestionParent/animation/constants.ts

@@ -0,0 +1,77 @@
+import type { Transition } from 'framer-motion';
+
+/**
+ * Animation contract — двухслойный chip + FLIP-spring layout (1:1 из ai-components).
+ *
+ * Per-property timing:
+ *   width / marginRight / scale  → sync, одна duration, один easing.
+ *   opacity                      → со stagger (visual ripple).
+ *   layout (FLIP)                → spring (110, 22, 1).
+ *
+ * Длительности:
+ *   enter width/scale  → 650ms     opacity → 450ms, stagger 60ms
+ *   exit  width/scale  → 550ms     opacity → 280ms, stagger 80ms
+ */
+
+/** easings:
+ *   enter — easeOutQuart
+ *   exit  — easeInQuart
+ *   bubble — easeOutBack overshoot ~5% для inner scale
+ */
+export const ENTER_EASE: Transition['ease'] = [0.22, 1, 0.36, 1];
+export const EXIT_EASE: Transition['ease'] = [0.64, 0, 0.78, 0];
+export const BUBBLE_ENTER_EASE: Transition['ease'] = [0.34, 1.5, 0.64, 1];
+
+export const ENTER_WIDTH_S = 0.65;
+export const ENTER_OPACITY_S = 0.45;
+
+export const EXIT_OPACITY_S = 0.28;
+export const EXIT_WIDTH_S = 0.55;
+
+export const STAGGER_FORWARD_OPACITY_S = 0.06;
+export const STAGGER_BACKWARD_OPACITY_S = 0.08;
+export const MAX_STAGGER_WINDOW_S = 0.5;
+
+export const GAP_PX = 4;
+
+export const layoutSpring: Transition = {
+  type: 'spring',
+  stiffness: 110,
+  damping: 22,
+  mass: 1,
+};
+
+export const cappedStagger = (idealPerChip: number, total: number, index: number): number => {
+  if (total <= 1) {
+    return 0;
+  }
+
+  const perChip = Math.min(idealPerChip, MAX_STAGGER_WINDOW_S / (total - 1));
+
+  return index * perChip;
+};
+
+const sizeTransition = (activated: boolean): Transition => ({
+  duration: activated ? ENTER_WIDTH_S : EXIT_WIDTH_S,
+  ease: activated ? ENTER_EASE : EXIT_EASE,
+});
+
+export const outerChipTransition = (activated: boolean): Transition => ({
+  width: sizeTransition(activated),
+  marginRight: sizeTransition(activated),
+  layout: layoutSpring,
+});
+
+export const innerChipTransition = (index: number, total: number, activated: boolean): Transition => ({
+  scale: {
+    duration: activated ? ENTER_WIDTH_S : EXIT_WIDTH_S,
+    ease: activated ? BUBBLE_ENTER_EASE : EXIT_EASE,
+  },
+  opacity: {
+    duration: activated ? ENTER_OPACITY_S : EXIT_OPACITY_S,
+    ease: activated ? ENTER_EASE : EXIT_EASE,
+    delay: activated
+      ? cappedStagger(STAGGER_FORWARD_OPACITY_S, total, index)
+      : cappedStagger(STAGGER_BACKWARD_OPACITY_S, total, total - 1 - index),
+  },
+});

package/src/AiSuggestionParent/animation/styles.module.scss

@@ -0,0 +1,25 @@
+@use '@cloud-ru/ds-figma-variables/build/scss/styles/styles.module' as base;
+
+.outerChip {
+  contain: layout;
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+}
+
+.innerChip {
+  will-change: transform, opacity;
+  transform-origin: center;
+  display: inline-flex;
+}
+
+.innerChipHidden {
+  pointer-events: none;
+}
+
+.triggerWrap {
+  display: inline-flex;
+  flex-shrink: 0;
+  margin-right: base.$sn-primitive-dimension-4;
+}

package/src/AiSuggestionParent/constants.ts

@@ -0,0 +1,10 @@
+export const CHILD_TYPE = {
+  Suggestion: 'suggestion',
+  Parent: 'parent',
+} as const;
+
+export const TEST_IDS = {
+  root: 'ai-suggestion-parent',
+  trigger: 'ai-suggestion-parent__trigger',
+  chevron: 'ai-suggestion-parent__chevron',
+} as const;

package/src/AiSuggestionParent/context/AiSuggestionParentGroupContext.tsx

@@ -0,0 +1,44 @@
+import { createContext, ReactNode, useCallback, useContext, useMemo, useState } from 'react';
+
+type AiSuggestionParentGroupContextValue = {
+  expandedKey: string | null;
+  requestExpand(key: string): void;
+  collapseKey(key: string): void;
+};
+
+const AiSuggestionParentGroupContext = createContext<AiSuggestionParentGroupContextValue | null>(null);
+
+export type AiSuggestionParentGroupProviderProps = {
+  children: ReactNode;
+  initialExpandedKey?: string | null;
+};
+
+export function AiSuggestionParentGroupProvider({
+  children,
+  initialExpandedKey = null,
+}: AiSuggestionParentGroupProviderProps) {
+  const [expandedKey, setExpandedKey] = useState<string | null>(initialExpandedKey);
+
+  const requestExpand = useCallback((key: string) => {
+    setExpandedKey(prev => (prev === key ? null : key));
+  }, []);
+
+  const collapseKey = useCallback((key: string) => {
+    setExpandedKey(prev => (prev === key ? null : prev));
+  }, []);
+
+  const value = useMemo(
+    () => ({
+      expandedKey,
+      requestExpand,
+      collapseKey,
+    }),
+    [collapseKey, expandedKey, requestExpand],
+  );
+
+  return <AiSuggestionParentGroupContext.Provider value={value}>{children}</AiSuggestionParentGroupContext.Provider>;
+}
+
+export function useAiSuggestionParentGroup() {
+  return useContext(AiSuggestionParentGroupContext);
+}

package/src/AiSuggestionParent/index.ts

@@ -0,0 +1,4 @@
+export * from './AiSuggestionParent';
+export { AiSuggestionParentChip } from './AiSuggestionParentChip';
+export { CHILD_TYPE, TEST_IDS as AI_SUGGESTION_PARENT_TEST_IDS } from './constants';
+export * from './types';