datocms-react-ui 2.1.0-alpha.0 → 2.1.0-alpha.2

package/src/SplitView/index.tsx

@@ -0,0 +1,256 @@
+import classNames from 'classnames';
+import React, {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { SplitViewPane, type SplitViewPaneProps } from './SplitViewPane';
+import { SashAction, SplitViewSash } from './SplitViewSash';
+import s from './styles.module.css.json';
+import { IAxis, ICacheSizes } from './types';
+
+type SplitViewProps = {
+  children: JSX.Element[];
+  allowResize?: boolean;
+  split?: 'vertical' | 'horizontal';
+  sizes: (string | number)[];
+  onChange: (sizes: number[]) => void;
+  onDragStart?: () => void;
+  onDragEnd?: () => void;
+  performanceMode?: boolean;
+  resizerSize?: number;
+  sashAction?: SashAction;
+};
+
+export const SplitView = ({
+  children,
+  sizes: propSizes,
+  allowResize = true,
+  split = 'vertical',
+  resizerSize = 10,
+  performanceMode = false,
+  onChange = () => null,
+  onDragStart = () => null,
+  onDragEnd = () => null,
+  sashAction,
+}: SplitViewProps) => {
+  const axis = useRef<IAxis>({ x: 0, y: 0 });
+  const wrapper = useRef<HTMLDivElement>(null);
+  const cacheSizes = useRef<ICacheSizes>({ sizes: [], sashPosSizes: [] });
+  const [wrapperRect, setWrapperRect] = useState<DOMRect | undefined>(
+    undefined,
+  );
+  const [isDragging, setDragging] = useState<boolean>(false);
+
+  useEffect(() => {
+    const resizeObserver = new ResizeObserver(() => {
+      if (wrapper?.current) {
+        setWrapperRect(wrapper.current.getBoundingClientRect());
+      }
+    });
+    resizeObserver.observe(wrapper.current!);
+    return () => {
+      resizeObserver.disconnect();
+    };
+  }, []);
+
+  const { sizeName, splitPos, splitAxis } = useMemo<{
+    sizeName: 'width' | 'height';
+    splitPos: 'left' | 'top';
+    splitAxis: 'x' | 'y';
+  }>(
+    () => ({
+      sizeName: split === 'vertical' ? 'width' : 'height',
+      splitPos: split === 'vertical' ? 'left' : 'top',
+      splitAxis: split === 'vertical' ? 'x' : 'y',
+    }),
+    [split],
+  );
+
+  const wrapSize: number = wrapperRect ? wrapperRect[sizeName] : 0;
+
+  // Get limit sizes via children
+  const paneLimitSizes = useMemo(
+    () =>
+      children.map((childNode) => {
+        const limits = [0, Infinity];
+        if (childNode.type === SplitViewPane) {
+          const { minSize, maxSize } = childNode.props as SplitViewPaneProps;
+          limits[0] = assertSize(minSize, wrapSize, 0);
+          limits[1] = assertSize(maxSize, wrapSize);
+        }
+        return limits as [number, number];
+      }),
+    [children, wrapSize],
+  );
+
+  const sizes = useMemo(() => {
+    let count = 0;
+    let curSum = 0;
+
+    const res = children.map((_child, index) => {
+      const size = clampSize(
+        assertSize(propSizes[index], wrapSize),
+        paneLimitSizes[index],
+      );
+      if (size === Infinity) {
+        count = count + 1;
+      } else {
+        curSum = curSum + size;
+      }
+      return size;
+    });
+
+    // resize or illegal size input,recalculate pane sizes
+    if (curSum > wrapSize || (!count && curSum < wrapSize)) {
+      const cacheNum = (curSum - wrapSize) / curSum;
+      return res.map((size) => {
+        return size === Infinity ? 0 : size - size * cacheNum;
+      });
+    }
+
+    if (count > 0) {
+      const average = (wrapSize - curSum) / count;
+      return res.map((size) => {
+        return size === Infinity ? average : size;
+      });
+    }
+
+    return res;
+  }, [
+    JSON.stringify(propSizes),
+    JSON.stringify(paneLimitSizes),
+    children.length,
+    wrapSize,
+  ]);
+
+  const sashPosSizes = useMemo(
+    () => sizes.reduce((a, b) => [...a, a[a.length - 1] + b], [0]),
+    [JSON.stringify(sizes)],
+  );
+
+  const handleMouseDown = useCallback(
+    (x: number, y: number) => {
+      document?.body?.classList?.add(s['SplitView--disable-select']);
+      axis.current = { x, y };
+      cacheSizes.current = { sizes, sashPosSizes };
+      setDragging(true);
+      onDragStart();
+    },
+    [onDragStart, sizes, sashPosSizes],
+  );
+
+  const handleMouseUp = useCallback(() => {
+    document?.body?.classList?.remove(s['SplitView--disable-select']);
+    setDragging(false);
+    onDragEnd();
+  }, [onDragEnd]);
+
+  const handleMouseMove = useCallback(
+    (x: number, y: number, i: number) => {
+      const curAxis = { x, y };
+      let distanceX = curAxis[splitAxis] - axis.current[splitAxis];
+
+      const leftBorder = -Math.min(
+        sizes[i] - paneLimitSizes[i][0],
+        paneLimitSizes[i + 1][1] - sizes[i + 1],
+      );
+      const rightBorder = Math.min(
+        sizes[i + 1] - paneLimitSizes[i + 1][0],
+        paneLimitSizes[i][1] - sizes[i],
+      );
+
+      if (distanceX < leftBorder) {
+        distanceX = leftBorder;
+      }
+      if (distanceX > rightBorder) {
+        distanceX = rightBorder;
+      }
+
+      const nextSizes = [...sizes];
+      nextSizes[i] += distanceX;
+      nextSizes[i + 1] -= distanceX;
+
+      onChange(nextSizes);
+    },
+    [paneLimitSizes, onChange],
+  );
+
+  const paneFollow = !(performanceMode && isDragging);
+  const paneSizes = paneFollow ? sizes : cacheSizes.current.sizes;
+  const panePoses = paneFollow ? sashPosSizes : cacheSizes.current.sashPosSizes;
+
+  return (
+    <div
+      className={classNames(
+        s.SplitView,
+        split === 'vertical' && s['SplitView--vertical'],
+        split === 'horizontal' && s['SplitView--horizontal'],
+        isDragging && s['SplitView--dragging'],
+      )}
+      ref={wrapper}
+    >
+      {children.map((childNode, childIndex) => {
+        const isPane = childNode.type === SplitViewPane;
+        const paneProps = isPane ? childNode.props : {};
+
+        return (
+          <SplitViewPane
+            // biome-ignore lint/suspicious/noArrayIndexKey: <explanation>
+            key={childIndex}
+            style={{
+              ...paneProps.style,
+              [sizeName]: paneSizes[childIndex],
+              [splitPos]: panePoses[childIndex],
+            }}
+          >
+            {isPane ? paneProps.children : childNode}
+          </SplitViewPane>
+        );
+      })}
+      {sashPosSizes.slice(1, -1).map((posSize, index) => (
+        <SplitViewSash
+          // biome-ignore lint/suspicious/noArrayIndexKey: <explanation>
+          key={index}
+          allowResize={allowResize}
+          split={split}
+          style={{
+            [sizeName]: resizerSize,
+            [splitPos]: posSize - resizerSize / 2,
+          }}
+          onMouseDown={handleMouseDown}
+          onMouseMove={(x, y) => handleMouseMove(x, y, index)}
+          onMouseUp={handleMouseUp}
+          action={sashAction}
+        />
+      ))}
+    </div>
+  );
+};
+
+/**
+ * Convert size to absolute number or Infinity
+ * SplitPane allows sizes in string and number, but the state sizes only support number,
+ * so convert string and number to number in here
+ * 'auto' -> divide the remaining space equally
+ * 'xxxpx' -> xxx
+ * 'xxx%' -> wrapper.size * xxx/100
+ *  xxx -> xxx
+ */
+function assertSize(
+  size: string | number | undefined,
+  sum: number,
+  defaultValue = Infinity,
+) {
+  if (typeof size === 'undefined') return defaultValue;
+  if (typeof size === 'number') return size;
+  if (size.endsWith('%')) return sum * (+size.replace('%', '') / 100);
+  if (size.endsWith('px')) return +size.replace('px', '');
+  return defaultValue;
+}
+
+function clampSize(size: number, minMax: [number, number]) {
+  return Math.max(minMax[0], Math.min(minMax[1], size));
+}

package/src/SplitView/styles.module.css

@@ -0,0 +1,22 @@
+.SplitView {
+  flex: 1;
+  height: 100%;
+  position: relative;
+  width: 100%;
+}
+
+.SplitView--dragging.SplitView--vertical {
+  cursor: col-resize;
+}
+
+.SplitView--dragging.SplitView--horizontal {
+  cursor: row-resize;
+}
+
+.SplitView--disable-select {
+  user-select: none;
+}
+
+.SplitView--disable-select .SplitViewPane {
+  pointer-events: none;
+}

package/src/SplitView/styles.module.css.json

@@ -0,0 +1 @@
+{"SplitView":"_SplitView_1oi17_1","SplitView--dragging":"_SplitView--dragging_1oi17_8","SplitView--vertical":"_SplitView--vertical_1oi17_8","SplitView--horizontal":"_SplitView--horizontal_1oi17_12","SplitView--disable-select":"_SplitView--disable-select_1oi17_16","SplitViewPane":"_SplitViewPane_1oi17_20"}

package/src/SplitView/types.ts

@@ -0,0 +1,9 @@
+export type IAxis = {
+  x: number;
+  y: number;
+};
+
+export type ICacheSizes = {
+  sizes: (string | number)[];
+  sashPosSizes: (string | number)[];
+};

package/src/Tooltip/Tooltip/index.tsx

@@ -0,0 +1,85 @@
+import * as React from 'react';
+import { TooltipContext, TooltipOptions, useTooltip } from '../utils';
+
+export type TooltipProps = {
+  children?: React.ReactNode;
+} & TooltipOptions;
+
+/**
+ * Tooltip wrapper component that provides context for TooltipTrigger and TooltipContent.
+ *
+ * This is a compound component pattern. The Tooltip component itself doesn't render anything,
+ * but provides the necessary context for its children (TooltipTrigger and TooltipContent).
+ *
+ * @example Basic tooltip
+ *
+ * Create a simple tooltip that appears when hovering over a button:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip>
+ *     <TooltipTrigger>
+ *       <Button>Hover me</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       This is helpful information!
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ *
+ * @example Tooltip with custom placement
+ *
+ * Control where the tooltip appears relative to its trigger using the `placement` prop:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip placement="right">
+ *     <TooltipTrigger>
+ *       <Button>Right tooltip</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       Appears on the right side
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ *
+ * @example Multiple tooltips
+ *
+ * Use multiple tooltips on the same page to provide contextual help for different actions:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <div style={{ display: 'flex', gap: 'var(--spacing-m)' }}>
+ *     <Tooltip>
+ *       <TooltipTrigger>
+ *         <Button leftIcon={<SaveIcon />} />
+ *       </TooltipTrigger>
+ *       <TooltipContent>
+ *         Save changes (⌘S)
+ *       </TooltipContent>
+ *     </Tooltip>
+ *
+ *     <Tooltip>
+ *       <TooltipTrigger>
+ *         <Button leftIcon={<DeleteIcon />} />
+ *       </TooltipTrigger>
+ *       <TooltipContent>
+ *         Delete item
+ *       </TooltipContent>
+ *     </Tooltip>
+ *   </div>
+ * </Canvas>;
+ * ```
+ */
+export function Tooltip({ children, ...options }: TooltipProps) {
+  // This can accept any props as options, e.g. `placement`,
+  // or other positioning options.
+  const tooltip = useTooltip(options);
+  return (
+    <TooltipContext.Provider value={tooltip}>
+      {children}
+    </TooltipContext.Provider>
+  );
+}

package/src/Tooltip/TooltipContent/index.tsx

@@ -0,0 +1,145 @@
+import {
+  FloatingPortal,
+  useDelayGroup,
+  useDelayGroupContext,
+  useMergeRefs,
+  useTransitionStyles,
+} from '@floating-ui/react';
+import * as React from 'react';
+import { Canvas, useCtx } from '../../Canvas';
+import {
+  getSharedPortalRoot,
+  releaseSharedPortalRoot,
+  useTooltipState,
+} from '../utils';
+import s from './styles.module.css.json';
+
+export type TooltipContentProps = {
+  children?: React.ReactNode;
+};
+
+/**
+ * TooltipContent contains the content displayed in the floating tooltip.
+ *
+ * The content is automatically wrapped in a Canvas component to inherit the DatoCMS
+ * theme and styling. The tooltip uses a portal to render outside the normal DOM
+ * hierarchy, ensuring proper positioning and z-index stacking.
+ *
+ * @example Simple text tooltip
+ *
+ * Display plain text in a tooltip to provide helpful information:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip>
+ *     <TooltipTrigger>
+ *       <Button>Delete</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       This action cannot be undone
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ *
+ * @example Rich content tooltip
+ *
+ * Include formatted content with custom styles for more detailed information:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip placement="right">
+ *     <TooltipTrigger>
+ *       <Button leftIcon={<HelpIcon />}>Help</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       <div>
+ *         <strong>Need assistance?</strong>
+ *         <p style={{ margin: '5px 0 0 0', fontSize: 'var(--font-size-xs)' }}>
+ *           Contact support@example.com
+ *         </p>
+ *       </div>
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ *
+ * @example Tooltip with keyboard shortcut
+ *
+ * Combine tooltips with the HotKey component to show keyboard shortcuts:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip>
+ *     <TooltipTrigger>
+ *       <Button leftIcon={<SaveIcon />}>Save</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       <HotKey hotkey="mod+s" label="Save changes" />
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ */
+export const TooltipContent = React.forwardRef<
+  HTMLDivElement,
+  TooltipContentProps
+>(function TooltipContent({ children }, propRef) {
+  const ctx = useCtx();
+  const state = useTooltipState();
+  const { isInstantPhase, currentId } = useDelayGroupContext();
+  const ref = useMergeRefs([state.refs.setFloating, propRef]);
+
+  // Use the shared portal root
+  const portalRootRef = React.useRef<HTMLDivElement | null>(null);
+
+  React.useEffect(() => {
+    // Get the shared portal root and increment ref count
+    portalRootRef.current = getSharedPortalRoot();
+
+    // Cleanup function to release the shared portal root
+    return () => {
+      releaseSharedPortalRoot();
+    };
+  }, []);
+
+  useDelayGroup(state.context, { id: state.context.floatingId });
+
+  const instantDuration = 0;
+  const duration = 250;
+
+  const { isMounted, styles } = useTransitionStyles(state.context, {
+    duration: isInstantPhase
+      ? {
+          open: instantDuration,
+          // `id` is this component's `id`
+          // `currentId` is the current group's `id`
+          close:
+            currentId === state.context.floatingId ? duration : instantDuration,
+        }
+      : duration,
+    initial: {
+      opacity: 0,
+    },
+  });
+
+  if (!isMounted) return null;
+
+  return (
+    <FloatingPortal root={portalRootRef}>
+      <Canvas ctx={ctx} noAutoResizer>
+        <div
+          ref={ref}
+          style={{
+            ...state.floatingStyles,
+            ...styles,
+          }}
+          {...state.getFloatingProps()}
+          className={s.tooltip}
+        >
+          {children}
+        </div>
+      </Canvas>
+    </FloatingPortal>
+  );
+});

package/src/Tooltip/TooltipContent/styles.module.css

@@ -0,0 +1,10 @@
+.tooltip {
+  padding: 10px 15px;
+  box-shadow: 0 1px 9px rgba(0, 0, 0, 0.2);
+  background: white;
+  border-radius: 4px;
+  max-width: 400px;
+  word-wrap: break-word;
+  overflow-wrap: break-word;
+  hyphens: auto;
+}

package/src/Tooltip/TooltipContent/styles.module.css.json

@@ -0,0 +1 @@
+{"tooltip":"_tooltip_3z5rn_1"}

package/src/Tooltip/TooltipDelayGroup/index.tsx

@@ -0,0 +1,128 @@
+import { FloatingDelayGroup } from '@floating-ui/react';
+import * as React from 'react';
+
+export type TooltipDelayGroupProps = {
+  children?: React.ReactNode;
+  /** The delay in milliseconds before a tooltip opens on hover (default: 1000) */
+  delay?: number | { open?: number; close?: number };
+  /** How long to wait in milliseconds before closing the group (default: 0) */
+  timeoutMs?: number;
+};
+
+/**
+ * TooltipDelayGroup synchronizes hover delays across multiple tooltips.
+ *
+ * When tooltips are wrapped in a delay group, hovering over the first tooltip
+ * will use the configured delay, but subsequent tooltips in the group will
+ * open instantly. This creates a smoother UX when users explore multiple
+ * interactive elements with tooltips.
+ *
+ * @example Basic delay group
+ *
+ * Group multiple tooltips together so they open instantly after the first one:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <TooltipDelayGroup delay={500}>
+ *     <div style={{ display: 'flex', gap: 'var(--spacing-m)' }}>
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button leftIcon={<SaveIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Save changes</TooltipContent>
+ *       </Tooltip>
+ *
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button leftIcon={<UndoIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Undo</TooltipContent>
+ *       </Tooltip>
+ *
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button leftIcon={<RedoIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Redo</TooltipContent>
+ *       </Tooltip>
+ *     </div>
+ *   </TooltipDelayGroup>
+ * </Canvas>;
+ * ```
+ *
+ * @example Custom delay configuration
+ *
+ * Configure different delays for opening and closing tooltips in the group:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <TooltipDelayGroup delay={{ open: 800, close: 200 }} timeoutMs={500}>
+ *     <div style={{ display: 'flex', gap: 'var(--spacing-s)' }}>
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button>Action 1</Button>
+ *         </TooltipTrigger>
+ *         <TooltipContent>First action</TooltipContent>
+ *       </Tooltip>
+ *
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button>Action 2</Button>
+ *         </TooltipTrigger>
+ *         <TooltipContent>Second action</TooltipContent>
+ *       </Tooltip>
+ *     </div>
+ *   </TooltipDelayGroup>
+ * </Canvas>;
+ * ```
+ *
+ * @example Toolbar with grouped tooltips
+ *
+ * Create a toolbar where hovering between tools feels instant and responsive:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <TooltipDelayGroup delay={600}>
+ *     <div style={{
+ *       display: 'flex',
+ *       gap: 'var(--spacing-xs)',
+ *       padding: 'var(--spacing-s)',
+ *       borderRadius: 'var(--border-radius-m)',
+ *       backgroundColor: 'var(--light-bg-color)'
+ *     }}>
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button buttonSize="s" leftIcon={<BoldIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Bold</TooltipContent>
+ *       </Tooltip>
+ *
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button buttonSize="s" leftIcon={<ItalicIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Italic</TooltipContent>
+ *       </Tooltip>
+ *
+ *       <Tooltip>
+ *         <TooltipTrigger>
+ *           <Button buttonSize="s" leftIcon={<UnderlineIcon />} />
+ *         </TooltipTrigger>
+ *         <TooltipContent>Underline</TooltipContent>
+ *       </Tooltip>
+ *     </div>
+ *   </TooltipDelayGroup>
+ * </Canvas>;
+ * ```
+ */
+export function TooltipDelayGroup({
+  children,
+  delay = 1000,
+  timeoutMs = 0,
+}: TooltipDelayGroupProps) {
+  return (
+    <FloatingDelayGroup delay={delay} timeoutMs={timeoutMs}>
+      {children}
+    </FloatingDelayGroup>
+  );
+}