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

package/src/Tooltip/TooltipTrigger/index.tsx

@@ -0,0 +1,71 @@
+import { useMergeRefs } from '@floating-ui/react';
+import * as React from 'react';
+import { useTooltipState } from '../utils';
+
+export type TooltipTriggerProps = {
+  children: React.ReactElement;
+};
+
+/**
+ * TooltipTrigger wraps the element that triggers the tooltip on hover/focus.
+ *
+ * The child must be a single React element that accepts ref and event handler props.
+ * Common triggers include buttons, icons, or other interactive elements.
+ *
+ * @example With Button component
+ *
+ * Wrap a button to show a tooltip when the user hovers over it:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip>
+ *     <TooltipTrigger>
+ *       <Button>Hover for info</Button>
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       Additional information appears here
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ *
+ * @example With icon button
+ *
+ * Use tooltips with icon-only buttons to explain their purpose:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <Tooltip placement="bottom">
+ *     <TooltipTrigger>
+ *       <Button buttonSize="s" leftIcon={<InfoIcon />} />
+ *     </TooltipTrigger>
+ *     <TooltipContent>
+ *       Click for more details
+ *     </TooltipContent>
+ *   </Tooltip>
+ * </Canvas>;
+ * ```
+ */
+export const TooltipTrigger = React.forwardRef<
+  HTMLElement,
+  TooltipTriggerProps
+>(function TooltipTrigger({ children, ...props }, propRef) {
+  const state = useTooltipState();
+
+  const childrenRef = (children as any).ref;
+  const ref = useMergeRefs([state.refs.setReference, propRef, childrenRef]);
+
+  if (!React.isValidElement(children)) {
+    throw new Error('TooltipTrigger children must be a valid React element');
+  }
+
+  return React.cloneElement(
+    children,
+    state.getReferenceProps({
+      ref,
+      ...props,
+      ...children.props,
+      'data-state': state.open ? 'open' : 'closed',
+    }),
+  );
+});

package/src/Tooltip/index.ts

@@ -0,0 +1,8 @@
+export { Tooltip } from './Tooltip';
+export type { TooltipProps } from './Tooltip';
+export { TooltipContent } from './TooltipContent';
+export type { TooltipContentProps } from './TooltipContent';
+export { TooltipDelayGroup } from './TooltipDelayGroup';
+export type { TooltipDelayGroupProps } from './TooltipDelayGroup';
+export { TooltipTrigger } from './TooltipTrigger';
+export type { TooltipTriggerProps } from './TooltipTrigger';

package/src/Tooltip/utils.ts

@@ -0,0 +1,176 @@
+import type { Placement } from '@floating-ui/react';
+import {
+  autoUpdate,
+  flip,
+  offset,
+  shift,
+  useDelayGroupContext,
+  useDismiss,
+  useFloating,
+  useFocus,
+  useHover,
+  useInteractions,
+  useRole,
+} from '@floating-ui/react';
+import * as React from 'react';
+
+// Create a single shared portal root for all tooltips
+let sharedPortalRoot: HTMLDivElement | null = null;
+let portalRefCount = 0;
+
+export function getSharedPortalRoot(): HTMLDivElement {
+  if (!sharedPortalRoot) {
+    sharedPortalRoot = document.createElement('div');
+    sharedPortalRoot.style.position = 'relative';
+    sharedPortalRoot.style.zIndex = '100000';
+    sharedPortalRoot.style.height = '0px';
+
+    // Insert as the first child of body
+    if (document.body.firstChild) {
+      document.body.insertBefore(sharedPortalRoot, document.body.firstChild);
+    } else {
+      document.body.appendChild(sharedPortalRoot);
+    }
+  }
+  portalRefCount++;
+  return sharedPortalRoot;
+}
+
+export function releaseSharedPortalRoot(): void {
+  portalRefCount--;
+  if (portalRefCount === 0 && sharedPortalRoot) {
+    if (sharedPortalRoot.parentNode) {
+      sharedPortalRoot.parentNode.removeChild(sharedPortalRoot);
+    }
+    sharedPortalRoot = null;
+  }
+}
+
+export interface TooltipOptions {
+  /** Whether the tooltip is initially open (uncontrolled mode) */
+  initialOpen?: boolean;
+  /** Placement of the tooltip relative to its trigger */
+  placement?: Placement;
+  /** Controlled open state */
+  open?: boolean;
+  /** Callback when open state changes (controlled mode) */
+  onOpenChange?: (open: boolean) => void;
+}
+
+/**
+ * Hook that manages tooltip state and positioning logic.
+ *
+ * This hook provides the core tooltip behavior including hover/focus detection,
+ * positioning, and accessibility features. Use this when you need full control
+ * over the tooltip structure.
+ *
+ * @example Basic tooltip hook usage
+ *
+ * Build a custom tooltip implementation using the hook directly for maximum flexibility:
+ *
+ * ```js
+ * function MyComponent() {
+ *   const tooltip = useTooltip({ placement: 'top' });
+ *
+ *   return (
+ *     <>
+ *       <button
+ *         ref={tooltip.refs.setReference}
+ *         {...tooltip.getReferenceProps()}
+ *       >
+ *         Hover me
+ *       </button>
+ *
+ *       {tooltip.open && (
+ *         <div
+ *           ref={tooltip.refs.setFloating}
+ *           style={tooltip.floatingStyles}
+ *           {...tooltip.getFloatingProps()}
+ *         >
+ *           Tooltip content
+ *         </div>
+ *       )}
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * @example Controlled tooltip
+ *
+ * Control the tooltip's open state programmatically for click-to-toggle behavior:
+ *
+ * ```js
+ * function ControlledTooltip() {
+ *   const [open, setOpen] = React.useState(false);
+ *   const tooltip = useTooltip({ open, onOpenChange: setOpen });
+ *
+ *   return (
+ *     <Canvas ctx={ctx}>
+ *       <button onClick={() => setOpen(!open)}>
+ *         Toggle tooltip
+ *       </button>
+ *     </Canvas>
+ *   );
+ * }
+ * ```
+ */
+export function useTooltip({
+  initialOpen = false,
+  placement = 'top',
+  open: controlledOpen,
+  onOpenChange: setControlledOpen,
+}: TooltipOptions = {}) {
+  const [uncontrolledOpen, setUncontrolledOpen] = React.useState(initialOpen);
+
+  const open = controlledOpen ?? uncontrolledOpen;
+  const setOpen = setControlledOpen ?? setUncontrolledOpen;
+
+  const { delay } = useDelayGroupContext();
+
+  const data = useFloating({
+    placement,
+    open,
+    onOpenChange: setOpen,
+    whileElementsMounted: autoUpdate,
+    middleware: [offset(5), flip(), shift()],
+  });
+
+  const context = data.context;
+
+  const hover = useHover(context, {
+    move: false,
+    enabled: controlledOpen == null,
+    delay,
+  });
+  const focus = useFocus(context, {
+    enabled: controlledOpen == null,
+  });
+  const dismiss = useDismiss(context);
+  const role = useRole(context, { role: 'tooltip' });
+
+  const interactions = useInteractions([hover, focus, dismiss, role]);
+
+  return React.useMemo(
+    () => ({
+      open,
+      setOpen,
+      ...interactions,
+      ...data,
+    }),
+    [open, setOpen, interactions, data],
+  );
+}
+
+type ContextType = ReturnType<typeof useTooltip> | null;
+
+export const TooltipContext = React.createContext<ContextType>(null);
+
+export const useTooltipState = () => {
+  const context = React.useContext(TooltipContext);
+
+  if (context == null) {
+    throw new Error('Tooltip components must be wrapped in <Tooltip />');
+  }
+
+  return context;
+};

package/src/VerticalSplit/index.tsx

@@ -0,0 +1,401 @@
+import classNames from 'classnames';
+import React, { useEffect, useRef, useState } from 'react';
+import { SplitView } from '../SplitView';
+import { SplitViewPane } from '../SplitView/SplitViewPane';
+import sashS from '../SplitView/SplitViewSash/styles.module.css.json';
+import { ChevronsLeftIcon, ChevronsRightIcon, SidebarFlipIcon } from '../icons';
+import s from './styles.module.css.json';
+
+const initialSidebarWidth = 220;
+
+export type VerticalSplitProps = {
+  mode?: 'overlay' | 'split';
+  minSize?: number | string;
+  maxSize?: number | string;
+  size?: number | string;
+  primaryPane: 'left' | 'right';
+  isSecondaryCollapsed?: boolean;
+  allowResize?: boolean;
+  children: [React.ReactNode, React.ReactNode];
+  onDragFinished?: (newSize: number) => void;
+  onSecondaryToggle?: (secondaryExpanded: boolean) => void;
+};
+
+type Size = string | number;
+
+function calculateSizes({
+  size,
+  primaryPane,
+  isSecondaryCollapsed,
+}: {
+  size: number | string;
+  primaryPane: 'left' | 'right';
+  isSecondaryCollapsed?: boolean;
+}): Size[] {
+  const realSize = isSecondaryCollapsed ? 20 : size;
+  return primaryPane === 'right' ? [realSize] : ['auto', realSize];
+}
+
+/**
+ * @example Resizable, left primary panel
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <div style={{ height: 500, position: 'relative' }}>
+ *     <VerticalSplit primaryPane="left" size="25%" minSize={220}>
+ *       <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+ *         <Toolbar>
+ *           <ToolbarStack stackSize="l">
+ *             <ToolbarTitle>Primary</ToolbarTitle>
+ *           </ToolbarStack>
+ *         </Toolbar>
+ *         <div
+ *           style={{
+ *             flex: '1',
+ *             display: 'flex',
+ *             justifyContent: 'center',
+ *             alignItems: 'center',
+ *             height: '150px',
+ *           }}
+ *         >
+ *           Main content
+ *         </div>
+ *       </div>
+ *       <div style={{ display: 'flex', flexDirection: 'column', height: '100%', borderLeft: '1px solid var(--border-color)' }}>
+ *         <Toolbar>
+ *           <ToolbarStack stackSize="l">
+ *             <ToolbarTitle>Secondary</ToolbarTitle>
+ *           </ToolbarStack>
+ *         </Toolbar>
+ *         <div
+ *           style={{
+ *             flex: '1',
+ *             display: 'flex',
+ *             justifyContent: 'center',
+ *             alignItems: 'center',
+ *             height: '150px',
+ *           }}
+ *         >
+ *           Sidebar
+ *         </div>
+ *       </div>
+ *     </VerticalSplit>
+ *   </div>
+ * </Canvas>;
+ * ```
+ *
+ * @example Resizable, right primary panel
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <div style={{ height: 500, position: 'relative' }}>
+ *     <VerticalSplit primaryPane="right" size="25%" minSize={220}>
+ *       <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+ *         <Toolbar>
+ *           <ToolbarStack stackSize="l">
+ *             <ToolbarTitle>Secondary</ToolbarTitle>
+ *           </ToolbarStack>
+ *         </Toolbar>
+ *         <div
+ *           style={{
+ *             flex: '1',
+ *             display: 'flex',
+ *             justifyContent: 'center',
+ *             alignItems: 'center',
+ *             height: '150px',
+ *           }}
+ *         >
+ *           Sidebar
+ *         </div>
+ *       </div>
+ *       <div style={{ display: 'flex', flexDirection: 'column', height: '100%', borderLeft: '1px solid var(--border-color)' }}>
+ *         <Toolbar>
+ *           <ToolbarStack stackSize="l">
+ *             <ToolbarTitle>Primary</ToolbarTitle>
+ *           </ToolbarStack>
+ *         </Toolbar>
+ *         <div
+ *           style={{
+ *             flex: '1',
+ *             display: 'flex',
+ *             justifyContent: 'center',
+ *             alignItems: 'center',
+ *             height: '150px',
+ *           }}
+ *         >
+ *           Main content
+ *         </div>
+ *       </div>
+ *     </VerticalSplit>
+ *   </div>
+ * </Canvas>;
+ * ```
+ *
+ * @example Collapsible
+ *
+ * ```js
+ *   <Canvas ctx={ctx}>
+ *    <div style={{ height: 500, position: 'relative' }}>
+ *      <StateManager initial={true}>
+ *        {(isCollapsed, setCollapsed) => (
+ *          <VerticalSplit
+ *            primaryPane="left"
+ *            size="25%"
+ *            minSize={220}
+ *            isSecondaryCollapsed={isCollapsed}
+ *            onSecondaryToggle={setCollapsed}
+ *          >
+ *            <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+ *              <Toolbar>
+ *                <ToolbarStack stackSize="l">
+ *                  <ToolbarTitle>Primary</ToolbarTitle>
+ *                </ToolbarStack>
+ *              </Toolbar>
+ *              <div
+ *                style={{
+ *                  flex: '1',
+ *                  display: 'flex',
+ *                  justifyContent: 'center',
+ *                  alignItems: 'center',
+ *                  height: '150px',
+ *                }}
+ *              >
+ *                Main content
+ *              </div>
+ *            </div>
+ *            <div
+ *              style={{
+ *                display: 'flex',
+ *                flexDirection: 'column',
+ *                height: '100%',
+ *                borderLeft: '1px solid var(--border-color)',
+ *              }}
+ *            >
+ *              <Toolbar>
+ *                <ToolbarStack stackSize="l">
+ *                  <ToolbarTitle>Secondary</ToolbarTitle>
+ *                </ToolbarStack>
+ *              </Toolbar>
+ *              <div
+ *                style={{
+ *                  flex: '1',
+ *                  display: 'flex',
+ *                  justifyContent: 'center',
+ *                  alignItems: 'center',
+ *                  height: '150px',
+ *                }}
+ *              >
+ *                Sidebar
+ *              </div>
+ *            </div>
+ *          </VerticalSplit>
+ *        )}
+ *      </StateManager>
+ *    </div>
+ *  </Canvas>;
+ * ```
+ *
+ * @example Overlay mode
+ *
+ * ```js
+ *   <Canvas ctx={ctx}>
+ *    <div style={{ height: 500, position: 'relative' }}>
+ *      <StateManager initial={true}>
+ *        {(isCollapsed, setCollapsed) => (
+ *          <VerticalSplit
+ *            mode="overlay"
+ *            primaryPane="left"
+ *            size="25%"
+ *            minSize={220}
+ *            isSecondaryCollapsed={isCollapsed}
+ *            onSecondaryToggle={setCollapsed}
+ *          >
+ *            <div style={{ display: 'flex', flexDirection: 'column', height: '100%' }}>
+ *              <Toolbar>
+ *                <ToolbarStack stackSize="l">
+ *                  <ToolbarTitle>Primary</ToolbarTitle>
+ *                </ToolbarStack>
+ *              </Toolbar>
+ *              <div
+ *                style={{
+ *                  flex: '1',
+ *                  display: 'flex',
+ *                  justifyContent: 'center',
+ *                  alignItems: 'center',
+ *                  height: '150px',
+ *                }}
+ *              >
+ *                Main content
+ *              </div>
+ *            </div>
+ *            <div
+ *              style={{
+ *                display: 'flex',
+ *                flexDirection: 'column',
+ *                height: '100%',
+ *                borderLeft: '1px solid var(--border-color)',
+ *              }}
+ *            >
+ *              <Toolbar>
+ *                <ToolbarStack stackSize="l">
+ *                  <ToolbarTitle>Secondary</ToolbarTitle>
+ *                </ToolbarStack>
+ *              </Toolbar>
+ *              <div
+ *                style={{
+ *                  flex: '1',
+ *                  display: 'flex',
+ *                  justifyContent: 'center',
+ *                  alignItems: 'center',
+ *                  height: '150px',
+ *                }}
+ *              >
+ *                Sidebar
+ *              </div>
+ *            </div>
+ *          </VerticalSplit>
+ *        )}
+ *      </StateManager>
+ *    </div>
+ *  </Canvas>;
+ * ```
+ */
+export function VerticalSplit({
+  mode = 'split',
+  minSize = 200,
+  maxSize,
+  size = initialSidebarWidth,
+  primaryPane,
+  children,
+  allowResize = true,
+  onDragFinished,
+  onSecondaryToggle,
+  isSecondaryCollapsed,
+}: VerticalSplitProps) {
+  const [sizes, setSizes] = useState<Size[]>(
+    calculateSizes({ size, primaryPane, isSecondaryCollapsed }),
+  );
+  const currentSizes = useRef<Size[]>(sizes);
+
+  const SashActionIcon = onSecondaryToggle
+    ? primaryPane === 'left'
+      ? isSecondaryCollapsed
+        ? SidebarFlipIcon
+        : ChevronsRightIcon
+      : isSecondaryCollapsed
+        ? ChevronsRightIcon
+        : ChevronsLeftIcon
+    : undefined;
+
+  useEffect(() => {
+    setSizes(calculateSizes({ size, primaryPane, isSecondaryCollapsed }));
+  }, [size, primaryPane, isSecondaryCollapsed]);
+
+  function handleChange(newSizes: Size[]) {
+    setSizes(newSizes);
+    currentSizes.current = newSizes;
+  }
+
+  function handleDragEnd() {
+    onDragFinished?.(currentSizes.current[0] as number);
+  }
+
+  function handleSecondaryClick() {
+    onSecondaryToggle?.(!isSecondaryCollapsed);
+  }
+
+  function renderPane(pane: 'left' | 'right') {
+    const isSecondaryPane = primaryPane !== pane;
+
+    return (
+      <SplitViewPane
+        {...(isSecondaryPane && !isSecondaryCollapsed
+          ? { minSize, maxSize }
+          : {})}
+      >
+        {isSecondaryPane && isSecondaryCollapsed ? (
+          <div
+            className={classNames(
+              s.VerticalSplitPane__expand,
+              s[`VerticalSplitPane__expand--${pane}`],
+            )}
+            onClick={handleSecondaryClick}
+          />
+        ) : (
+          children[pane === 'left' ? 0 : 1]
+        )}
+      </SplitViewPane>
+    );
+  }
+
+  if (mode === 'overlay' && !isSecondaryCollapsed && SashActionIcon) {
+    const primaryPaneChild = children[primaryPane === 'left' ? 0 : 1];
+    const secondaryPaneChild = children[primaryPane === 'left' ? 1 : 0];
+
+    return (
+      <>
+        <div
+          className={s.VerticalSplitPaneOverlay}
+          onClick={handleSecondaryClick}
+        >
+          <div
+            className={classNames(
+              s.VerticalSplitPaneOverlay__secondary,
+              s[
+                `VerticalSplitPaneOverlay__secondary--${
+                  primaryPane === 'left' ? 'right' : 'left'
+                }`
+              ],
+            )}
+            style={{
+              width: size,
+              maxWidth: maxSize,
+              minWidth: minSize,
+            }}
+            onClick={(e) => {
+              e.stopPropagation();
+            }}
+          >
+            {secondaryPaneChild}
+            <div className={s.VerticalSplitPaneOverlay__sash}>
+              <div
+                className={sashS.SplitViewSash__content}
+                onClick={handleSecondaryClick}
+              >
+                <div className={sashS.SplitViewSash__content__button}>
+                  <SashActionIcon />
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+        <div
+          className={classNames(
+            s.VerticalSplitPaneOverlay__primary,
+            s[`VerticalSplitPaneOverlay__primary--${primaryPane}`],
+          )}
+        >
+          {primaryPaneChild}
+        </div>
+      </>
+    );
+  }
+
+  return (
+    <SplitView
+      allowResize={!isSecondaryCollapsed && allowResize}
+      sizes={sizes}
+      onChange={handleChange}
+      onDragEnd={handleDragEnd}
+      sashAction={
+        SashActionIcon && {
+          icon: <SashActionIcon />,
+          onClick: handleSecondaryClick,
+        }
+      }
+    >
+      {renderPane('left')}
+      {renderPane('right')}
+    </SplitView>
+  );
+}