datocms-react-ui 2.0.17 → 2.0.19

package/dist/types/Tooltip/utils.d.ts

@@ -0,0 +1,166 @@
+import type { Placement } from '@floating-ui/react';
+import * as React from 'react';
+export declare function getSharedPortalRoot(): HTMLDivElement;
+export declare function releaseSharedPortalRoot(): void;
+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 declare function useTooltip({ initialOpen, placement, open: controlledOpen, onOpenChange: setControlledOpen, }?: TooltipOptions): {
+    placement: Placement;
+    strategy: import("@floating-ui/utils").Strategy;
+    middlewareData: import("@floating-ui/core").MiddlewareData;
+    x: number;
+    y: number;
+    isPositioned: boolean;
+    update: () => void;
+    floatingStyles: React.CSSProperties;
+    refs: {
+        reference: React.MutableRefObject<import("@floating-ui/react-dom").ReferenceType | null>;
+        floating: React.MutableRefObject<HTMLElement | null>;
+        setReference: (node: import("@floating-ui/react-dom").ReferenceType | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+    } & import("@floating-ui/react").ExtendedRefs<import("@floating-ui/react").ReferenceType>;
+    elements: {
+        reference: import("@floating-ui/react-dom").ReferenceType | null;
+        floating: HTMLElement | null;
+    } & import("@floating-ui/react").ExtendedElements<import("@floating-ui/react").ReferenceType>;
+    context: {
+        x: number;
+        y: number;
+        placement: Placement;
+        strategy: import("@floating-ui/utils").Strategy;
+        middlewareData: import("@floating-ui/core").MiddlewareData;
+        isPositioned: boolean;
+        update: () => void;
+        floatingStyles: React.CSSProperties;
+        open: boolean;
+        onOpenChange: (open: boolean, event?: Event | undefined, reason?: import("@floating-ui/react").OpenChangeReason | undefined) => void;
+        events: import("@floating-ui/react").FloatingEvents;
+        dataRef: React.MutableRefObject<import("@floating-ui/react").ContextData>;
+        nodeId: string | undefined;
+        floatingId: string | undefined;
+        refs: import("@floating-ui/react").ExtendedRefs<import("@floating-ui/react").ReferenceType>;
+        elements: import("@floating-ui/react").ExtendedElements<import("@floating-ui/react").ReferenceType>;
+    };
+    getReferenceProps: (userProps?: React.HTMLProps<Element> | undefined) => Record<string, unknown>;
+    getFloatingProps: (userProps?: React.HTMLProps<HTMLElement> | undefined) => Record<string, unknown>;
+    getItemProps: (userProps?: (Omit<React.HTMLProps<HTMLElement>, "selected" | "active"> & {
+        active?: boolean | undefined;
+        selected?: boolean | undefined;
+    }) | undefined) => Record<string, unknown>;
+    open: boolean;
+    setOpen: (open: boolean) => void;
+};
+declare type ContextType = ReturnType<typeof useTooltip> | null;
+export declare const TooltipContext: React.Context<ContextType>;
+export declare const useTooltipState: () => {
+    placement: Placement;
+    strategy: import("@floating-ui/utils").Strategy;
+    middlewareData: import("@floating-ui/core").MiddlewareData;
+    x: number;
+    y: number;
+    isPositioned: boolean;
+    update: () => void;
+    floatingStyles: React.CSSProperties;
+    refs: {
+        reference: React.MutableRefObject<import("@floating-ui/react-dom").ReferenceType | null>;
+        floating: React.MutableRefObject<HTMLElement | null>;
+        setReference: (node: import("@floating-ui/react-dom").ReferenceType | null) => void;
+        setFloating: (node: HTMLElement | null) => void;
+    } & import("@floating-ui/react").ExtendedRefs<import("@floating-ui/react").ReferenceType>;
+    elements: {
+        reference: import("@floating-ui/react-dom").ReferenceType | null;
+        floating: HTMLElement | null;
+    } & import("@floating-ui/react").ExtendedElements<import("@floating-ui/react").ReferenceType>;
+    context: {
+        x: number;
+        y: number;
+        placement: Placement;
+        strategy: import("@floating-ui/utils").Strategy;
+        middlewareData: import("@floating-ui/core").MiddlewareData;
+        isPositioned: boolean;
+        update: () => void;
+        floatingStyles: React.CSSProperties;
+        open: boolean;
+        onOpenChange: (open: boolean, event?: Event | undefined, reason?: import("@floating-ui/react").OpenChangeReason | undefined) => void;
+        events: import("@floating-ui/react").FloatingEvents;
+        dataRef: React.MutableRefObject<import("@floating-ui/react").ContextData>;
+        nodeId: string | undefined;
+        floatingId: string | undefined;
+        refs: import("@floating-ui/react").ExtendedRefs<import("@floating-ui/react").ReferenceType>;
+        elements: import("@floating-ui/react").ExtendedElements<import("@floating-ui/react").ReferenceType>;
+    };
+    getReferenceProps: (userProps?: React.HTMLProps<Element> | undefined) => Record<string, unknown>;
+    getFloatingProps: (userProps?: React.HTMLProps<HTMLElement> | undefined) => Record<string, unknown>;
+    getItemProps: (userProps?: (Omit<React.HTMLProps<HTMLElement>, "selected" | "active"> & {
+        active?: boolean | undefined;
+        selected?: boolean | undefined;
+    }) | undefined) => Record<string, unknown>;
+    open: boolean;
+    setOpen: (open: boolean) => void;
+};
+export {};

package/dist/types/index.d.ts

@@ -9,6 +9,7 @@ export * from './FieldHint';
 export * from './FieldWrapper';
 export * from './Form';
 export * from './FormLabel';
+export * from './HotKey';
 export * from './icons';
 export * from './Section';
 export * from './SelectField';
@@ -23,6 +24,7 @@ export * from './TextareaInput';
 export * from './TextField';
 export * from './TextInput';
 export * from './Toolbar';
+export * from './Tooltip';
 export * from './useClickOutside';
 export * from './useMediaQuery';
 export * from './VerticalSplit';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "datocms-react-ui",
-  "version": "2.0.17",
+  "version": "2.0.19",
   "description": "React components to use inside DatoCMS plugins",
   "keywords": [
     "datocms",
@@ -40,8 +40,9 @@
     "url": "https://github.com/datocms/plugins-sdk/issues"
   },
   "dependencies": {
+    "@floating-ui/react": "^0.27.16",
     "classnames": "^2.3.1",
-    "datocms-plugin-sdk": "^2.0.17",
+    "datocms-plugin-sdk": "^2.0.18",
     "react-intersection-observer": "^8.31.0",
     "react-select": "^5.2.1",
     "scroll-into-view-if-needed": "^2.2.20"
@@ -57,5 +58,5 @@
     "postcss-nested": "^5.0.6",
     "typedoc": "^0.26.7"
   },
-  "gitHead": "ce4d1125e8f52a499965e5aad358ffd78d9cc8fd"
+  "gitHead": "136cd08943c66f818b29e51313acc009f26163e8"
 }

package/src/HotKey/index.tsx

@@ -0,0 +1,95 @@
+import * as React from 'react';
+import styles from './styles.module.css.json';
+
+const isMac = navigator.platform.indexOf('Mac') > -1;
+const modifierKey = isMac ? '⌘' : 'Ctrl';
+
+export type HotKeyProps = {
+  /**
+   * Keyboard shortcut string. Use "mod" for platform-specific modifier (Cmd on Mac, Ctrl elsewhere).
+   * Separate keys with "+". Examples: "mod+s", "mod+shift+p", "alt+enter"
+   */
+  hotkey: string;
+  /** Optional label to display before the key combination */
+  label?: string;
+};
+
+/**
+ * HotKey component displays keyboard shortcuts in a platform-aware format.
+ *
+ * The component automatically detects the user's platform and renders appropriate
+ * modifier key symbols (⌘ for Mac, Ctrl for Windows/Linux).
+ *
+ * @example Basic usage
+ *
+ * Display a simple keyboard shortcut without a label:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <HotKey hotkey="mod+s" />
+ * </Canvas>;
+ * ```
+ *
+ * @example With label
+ *
+ * Include a descriptive label to explain what the keyboard shortcut does:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <HotKey hotkey="mod+s" label="Save" />
+ * </Canvas>;
+ * ```
+ *
+ * @example Multiple hotkeys
+ *
+ * Display a list of keyboard shortcuts with labels for documenting available commands:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-m)' }}>
+ *     <HotKey hotkey="mod+c" label="Copy" />
+ *     <HotKey hotkey="mod+v" label="Paste" />
+ *     <HotKey hotkey="mod+shift+z" label="Redo" />
+ *     <HotKey hotkey="alt+enter" label="Submit" />
+ *   </div>
+ * </Canvas>;
+ * ```
+ *
+ * @example Platform-specific rendering
+ *
+ * The component automatically adapts modifier keys based on the user's platform:
+ * - `mod` renders as `⌘` on Mac and `Ctrl` on Windows/Linux
+ * - `alt` renders as `⌥` on Mac and `Alt` on Windows/Linux
+ *
+ * This ensures the correct symbols are displayed for the user's operating system:
+ *
+ * ```js
+ * <Canvas ctx={ctx}>
+ *   <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-m)' }}>
+ *     <HotKey hotkey="mod+k" label="Open command palette" />
+ *     <HotKey hotkey="alt+enter" label="Submit form" />
+ *     <HotKey hotkey="mod+alt+f" label="Find and replace" />
+ *   </div>
+ * </Canvas>;
+ * ```
+ */
+export function HotKey({ hotkey, label }: HotKeyProps) {
+  const keys = hotkey
+    .replace('mod', modifierKey)
+    .replace('alt', isMac ? '⌥' : 'Alt')
+    .split(/\+/)
+    .map((e) => e.charAt(0).toUpperCase() + e.slice(1));
+
+  return (
+    <div className={styles.hotKey}>
+      {label && <span className={styles.label}>{label}</span>}
+      <div className={styles.keys}>
+        {keys.map((key) => (
+          <span key={key} className={styles.hotKeyKey}>
+            {key}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/HotKey/styles.module.css

@@ -0,0 +1,22 @@
+.hotKey {
+  display: inline-flex;
+  align-items: center;
+  gap: 15px;
+}
+
+.label {
+  display: flex;
+  align-items: center;
+}
+
+.keys {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+}
+
+.hotKeyKey {
+  padding: 5px 8px;
+  background: var(--light-color);
+  border-radius: 3px;
+}

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

@@ -0,0 +1 @@
+{"hotKey":"_hotKey_1eko8_1","label":"_label_1eko8_7","keys":"_keys_1eko8_12","hotKeyKey":"_hotKeyKey_1eko8_18"}

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"}