@moises.ai/design-system 4.18.1 → 4.18.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moises.ai/design-system",
-  "version": "4.18.1",
+  "version": "4.18.2",
   "description": "Design System package based on @radix-ui/themes with custom defaults",
   "private": false,
   "type": "module",

package/src/components/Knob/Knob.jsx

@@ -1,6 +1,6 @@
 import styles from './Knob.module.css'
 import classNames from 'classnames'
-import { useMemo, useState } from 'react'
+import { useEffect, useMemo, useRef, useState } from 'react'
 import { useKnob } from './useKnob'
 import {
   KNOB_CENTER_X,
@@ -11,6 +11,7 @@ import {
 } from './constants'
 import { getActiveDotIndex, getPointerProperties } from './utils'
 import React from 'react'
+import { Tooltip } from '../Tooltip/Tooltip'
 
 export const Knob = ({
   className,
@@ -19,13 +20,22 @@ export const Knob = ({
   disabled,
   clickableDots = false,
   dots = [],
+  showTooltip = true,
+  tooltipDelayDuration = 0,
+  tooltipCloseDelay = 500,
+  formatValue,
 }) => {
   const [hoveredDot, setHoveredDot] = useState(null)
+  const [isHovering, setIsHovering] = useState(false)
+  const openTimeoutRef = useRef(null)
+  const closeTimeoutRef = useRef(null)
+  const tooltipTimingRef = useRef({
+    tooltipDelayDuration,
+    tooltipCloseDelay,
+  })
+  tooltipTimingRef.current = { tooltipDelayDuration, tooltipCloseDelay }
 
-  if (!dots || dots.length === 0) {
-    console.warn('Knob: dots prop is required and must be a non-empty array')
-    return null
-  }
+  const hasDots = Array.isArray(dots) && dots.length > 0
 
   const defaultDot = useMemo(() => {
     return (
@@ -50,10 +60,69 @@ export const Knob = ({
     return getActiveDotIndex(value, dots)
   }, [value, dots])
 
+  const activeDot = useMemo(() => {
+    if (typeof value === 'object' && value !== null) return value
+    return dots?.find((dot) => dot.position === activeDotIndex) ?? null
+  }, [value, dots, activeDotIndex])
+
   const { pointerRotation, pointerColor } = useMemo(() => {
     return getPointerProperties(activeDotIndex, disabled)
   }, [activeDotIndex, disabled])
 
+  useEffect(() => {
+    return () => {
+      if (openTimeoutRef.current != null) clearTimeout(openTimeoutRef.current)
+      if (closeTimeoutRef.current != null) clearTimeout(closeTimeoutRef.current)
+    }
+  }, [])
+
+  if (!hasDots) {
+    console.warn('Knob: dots prop is required and must be a non-empty array')
+    return null
+  }
+
+  const clearOpenTimeout = () => {
+    if (openTimeoutRef.current != null) {
+      clearTimeout(openTimeoutRef.current)
+      openTimeoutRef.current = null
+    }
+  }
+
+  const clearCloseTimeout = () => {
+    if (closeTimeoutRef.current != null) {
+      clearTimeout(closeTimeoutRef.current)
+      closeTimeoutRef.current = null
+    }
+  }
+
+  const handlePointerEnter = () => {
+    if (disabled) return
+    clearCloseTimeout()
+    clearOpenTimeout()
+    const { tooltipDelayDuration: delay } = tooltipTimingRef.current
+    if (delay <= 0) {
+      setIsHovering(true)
+      return
+    }
+    openTimeoutRef.current = setTimeout(() => {
+      openTimeoutRef.current = null
+      setIsHovering(true)
+    }, delay)
+  }
+
+  const handlePointerLeave = () => {
+    clearOpenTimeout()
+    const { tooltipCloseDelay: delay } = tooltipTimingRef.current
+    if (delay <= 0) {
+      setIsHovering(false)
+      return
+    }
+    closeTimeoutRef.current = setTimeout(() => {
+      closeTimeoutRef.current = null
+      setIsHovering(false)
+    }, delay)
+  }
+
   const getDotColor = (dotConfig) => {
     const colorConfig = dotColors[dotConfig.color] || dotColors.neutral
     const isActive = dotConfig.position === activeDotIndex
@@ -72,100 +141,125 @@ export const Knob = ({
     }
   }
 
-  return (
+  const displayValue = formatValue
+    ? formatValue(activeDot ?? value)
+    : (activeDot?.label ?? activeDot?.value ?? activeDotIndex)
+
+  const tooltipOpen = !disabled && (isHovering || isDragging)
+
+  const knob = (
     <div
-      ref={containerRef}
-      className={classNames(styles.content, className)}
-      data-no-drag="true"
-      onClick={handleClick}
-      style={{ cursor: disabled ? 'default' : 'ns-resize' }}
+      className={classNames(
+        styles.pan,
+        isDragging && styles.active,
+        disabled && styles.disabled,
+      )}
+      onPointerEnter={handlePointerEnter}
+      onPointerLeave={handlePointerLeave}
     >
-      <div
-        className={classNames(
-          styles.pan,
-          isDragging && styles.active,
-          disabled && styles.disabled,
-        )}
-      >
-        <svg width={39} height={39} viewBox="0 0 39 39" fill="none">
-          {/* Background and outline */}
-          <circle cx={KNOB_CENTER_X} cy={KNOB_CENTER_Y} r={KNOB_RADIUS} />
-          <circle
-            cx={KNOB_CENTER_X}
-            cy={KNOB_CENTER_Y}
-            r={KNOB_RADIUS + 0.5}
-            stroke="#D3EDF8"
-            strokeOpacity={0.113725}
+      <svg width={39} height={39} viewBox="0 0 39 39" fill="none">
+        {/* Background and outline */}
+        <circle cx={KNOB_CENTER_X} cy={KNOB_CENTER_Y} r={KNOB_RADIUS} />
+        <circle
+          cx={KNOB_CENTER_X}
+          cy={KNOB_CENTER_Y}
+          r={KNOB_RADIUS + 0.5}
+          stroke="#D3EDF8"
+          strokeOpacity={0.113725}
+        />
+
+        {/* Pointer at the end of the arc */}
+        <g
+          transform={`rotate(${pointerRotation} ${KNOB_CENTER_X} ${KNOB_CENTER_Y})`}
+        >
+          <path
+            d="M19.5 4.5 L19.5 12"
+            stroke={pointerColor}
+            strokeWidth={1}
+            transform="rotate(90 19.5 19.5)"
           />
+        </g>
+
+        {/* dots around the knob */}
+        {dots?.map((dotConfig) => {
+          const dot = dotPositions[dotConfig.position]
+          if (!dot) return null
 
-          {/* Pointer at the end of the arc */}
-          <g
-            transform={`rotate(${pointerRotation} ${KNOB_CENTER_X} ${KNOB_CENTER_Y})`}
-          >
-            <path
-              d="M19.5 4.5 L19.5 12"
-              stroke={pointerColor}
-              strokeWidth={1}
-              transform="rotate(90 19.5 19.5)"
-            />
-          </g>
-
-          {/* dots around the knob */}
-          {dots?.map((dotConfig) => {
-            const dot = dotPositions[dotConfig.position]
-            if (!dot) return null
-
-            const fillColor = getDotColor(dotConfig)
-            // only clickable if not disabled
-            const isClickable = clickableDots && !disabled
-
-            return (
-              <React.Fragment key={`dot-${dotConfig.position}`}>
-                {isClickable && (
-                  <circle
-                    cx={dot.x}
-                    cy={dot.y}
-                    r={4}
-                    style={{
-                      cursor: 'pointer',
-                      pointerEvents: 'all',
-                    }}
-                    onMouseEnter={() => setHoveredDot(dotConfig.position)}
-                    onMouseLeave={() => setHoveredDot(null)}
-                    onClick={(e) => {
-                      e.stopPropagation()
-                      handleDotClick(dotConfig.position)
-                    }}
-                  />
-                )}
+          const fillColor = getDotColor(dotConfig)
+          // only clickable if not disabled
+          const isClickable = clickableDots && !disabled
+
+          return (
+            <React.Fragment key={`dot-${dotConfig.position}`}>
+              {isClickable && (
                 <circle
                   cx={dot.x}
                   cy={dot.y}
-                  r={1}
-                  fill={fillColor}
+                  r={4}
                   style={{
-                    cursor: isClickable ? 'pointer' : 'default',
-                    transition: 'fill 0.2s ease',
-                    pointerEvents: isClickable ? 'none' : 'all',
-                  }}
-                  onMouseEnter={() => {
-                    if (isClickable) setHoveredDot(dotConfig.position)
-                  }}
-                  onMouseLeave={() => {
-                    if (isClickable) setHoveredDot(null)
+                    cursor: 'pointer',
+                    pointerEvents: 'all',
                   }}
+                  onMouseEnter={() => setHoveredDot(dotConfig.position)}
+                  onMouseLeave={() => setHoveredDot(null)}
                   onClick={(e) => {
-                    if (isClickable) {
-                      e.stopPropagation()
-                      handleDotClick(dotConfig.position)
-                    }
+                    e.stopPropagation()
+                    handleDotClick(dotConfig.position)
                   }}
                 />
-              </React.Fragment>
-            )
-          })}
-        </svg>
-      </div>
+              )}
+              <circle
+                cx={dot.x}
+                cy={dot.y}
+                r={1}
+                fill={fillColor}
+                style={{
+                  cursor: isClickable ? 'pointer' : 'default',
+                  transition: 'fill 0.2s ease',
+                  pointerEvents: isClickable ? 'none' : 'all',
+                }}
+                onMouseEnter={() => {
+                  if (isClickable) setHoveredDot(dotConfig.position)
+                }}
+                onMouseLeave={() => {
+                  if (isClickable) setHoveredDot(null)
+                }}
+                onClick={(e) => {
+                  if (isClickable) {
+                    e.stopPropagation()
+                    handleDotClick(dotConfig.position)
+                  }
+                }}
+              />
+            </React.Fragment>
+          )
+        })}
+      </svg>
+    </div>
+  )
+
+  return (
+    <div
+      ref={containerRef}
+      className={classNames(styles.content, className)}
+      data-no-drag="true"
+      onClick={handleClick}
+      style={{ cursor: disabled ? 'default' : 'ns-resize' }}
+    >
+      {showTooltip ? (
+        <Tooltip
+          content={displayValue}
+          open={tooltipOpen}
+          delayDuration={tooltipDelayDuration}
+          side="bottom"
+          align="center"
+          sideOffset={3}
+        >
+          {knob}
+        </Tooltip>
+      ) : (
+        knob
+      )}
     </div>
   )
 }

package/src/components/Knob/Knob.stories.jsx

@@ -21,6 +21,8 @@ export default {
           '      value={selectedDot}\n' +
           '      onChange={setSelectedDot}\n' +
           '      clickableDots={true}\n' +
+          '      tooltipDelayDuration={0}\n' +
+          '      tooltipCloseDelay={500}\n' +
           '      dots={[\n' +
           '        { position: 0, color: "neutral", default: true, label: "Normal", value: "NORMAL" },\n' +
           '        { position: 2, color: "red", label: "High", value: "HIGH" },\n' +
@@ -43,11 +45,18 @@ export default {
           '- `7`: 10h30\n\n' +
           '## Clickable Dots\n\n' +
           'When `clickableDots={true}`, clicking on a dot will set the knob value to point to that position.\n\n' +
+          '## Tooltip\n\n' +
+          'By default the knob shows a tooltip with the active dot `label` (or `value`) on hover/drag. Use `tooltipDelayDuration` and `tooltipCloseDelay` to control open/close timing, or `showTooltip={false}` to hide it.\n\n' +
           '## Object Return\n\n' +
           'The `onChange` callback now receives the complete dot object including all properties like `label`, `value`, `position`, `color`, etc.',
       },
     },
   },
+  args: {
+    showTooltip: true,
+    tooltipDelayDuration: 0,
+    tooltipCloseDelay: 500,
+  },
   argTypes: {
     value: {
       description:
@@ -101,6 +110,30 @@ export default {
         type: { summary: 'string' },
       },
     },
+    showTooltip: {
+      control: 'boolean',
+      description: 'Shows a tooltip with the active dot label/value on hover/drag',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: true },
+      },
+    },
+    tooltipDelayDuration: {
+      control: 'number',
+      description: 'Ms before the tooltip opens on hover',
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: 0 },
+      },
+    },
+    tooltipCloseDelay: {
+      control: 'number',
+      description: 'Ms the tooltip stays open after the pointer leaves',
+      table: {
+        type: { summary: 'number' },
+        defaultValue: { summary: 500 },
+      },
+    },
   },
   tags: ['autodocs'],
 }
@@ -114,10 +147,10 @@ export const Default = {
         value={value}
         onChange={setValue}
         dots={[
-          { position: 0, color: 'neutral', default: true },
-          { position: 2, color: 'red' },
-          { position: 4, color: 'neutral' },
-          { position: 6, color: 'red' },
+          { position: 0, color: 'neutral', default: true, label: 'Normal' },
+          { position: 2, color: 'red', label: 'High' },
+          { position: 4, color: 'neutral', label: 'Low' },
+          { position: 6, color: 'red', label: 'Very High' },
         ]}
       />
     )
@@ -195,16 +228,98 @@ export const Disabled = {
         onChange={setValue}
         disabled={true}
         dots={[
-          { position: 0, color: 'neutral', default: true },
-          { position: 2, color: 'red' },
-          { position: 4, color: 'neutral' },
-          { position: 6, color: 'red' },
+          { position: 0, color: 'neutral', default: true, label: 'Normal' },
+          { position: 2, color: 'red', label: 'High' },
+          { position: 4, color: 'neutral', label: 'Low' },
+          { position: 6, color: 'red', label: 'Very High' },
+        ]}
+      />
+    )
+  },
+}
+
+export const WithoutTooltip = {
+  args: {
+    showTooltip: false,
+  },
+  render: (args) => {
+    const [value, setValue] = useState(null)
+    return (
+      <Knob
+        {...args}
+        value={value}
+        onChange={setValue}
+        dots={[
+          { position: 0, color: 'neutral', default: true, label: 'Normal' },
+          { position: 2, color: 'red', label: 'High' },
+          { position: 4, color: 'neutral', label: 'Low' },
+          { position: 6, color: 'red', label: 'Very High' },
         ]}
       />
     )
   },
 }
 
+export const TooltipTiming = {
+  name: 'Tooltip timing',
+  args: {
+    tooltipDelayDuration: 200,
+    tooltipCloseDelay: 500,
+  },
+  render: (args) => {
+    const [value, setValue] = useState(null)
+    return (
+      <Flex direction="column" align="center" gap="2">
+        <Knob
+          {...args}
+          value={value}
+          onChange={setValue}
+          clickableDots={true}
+          dots={[
+            {
+              position: 0,
+              color: 'neutral',
+              default: true,
+              label: 'Normal',
+              value: 'NORMAL',
+            },
+            {
+              position: 2,
+              color: 'red',
+              label: 'High',
+              value: 'HIGH',
+            },
+            {
+              position: 4,
+              color: 'neutral',
+              label: 'Low',
+              value: 'LOW',
+            },
+            {
+              position: 6,
+              color: 'red',
+              label: 'Very High',
+              value: 'VERY_HIGH',
+            },
+          ]}
+        />
+        <Text size="1" color="gray">
+          Opens after {args.tooltipDelayDuration}ms · closes{' '}
+          {args.tooltipCloseDelay}ms after leave
+        </Text>
+      </Flex>
+    )
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Adjust `tooltipDelayDuration` (open) and `tooltipCloseDelay` (close grace) via controls.',
+      },
+    },
+  },
+}
+
 export const WithClickableDots = {
   render: (args) => {
     const [value, setValue] = useState(null)
@@ -217,10 +332,10 @@ export const WithClickableDots = {
           onChange={setValue}
           clickableDots={true}
           dots={[
-            { position: 0, color: 'neutral', default: true },
-            { position: 2, color: 'red' },
-            { position: 4, color: 'neutral' },
-            { position: 6, color: 'red' },
+            { position: 0, color: 'neutral', default: true, label: 'Normal' },
+            { position: 2, color: 'red', label: 'High' },
+            { position: 4, color: 'neutral', label: 'Low' },
+            { position: 6, color: 'red', label: 'Very High' },
           ]}
         />
         <Text>
@@ -241,14 +356,14 @@ export const FullRotation = {
         onChange={setValue}
         clickableDots={true}
         dots={[
-          { position: 0, color: 'neutral' }, // 12h
-          { position: 1, color: 'neutral' }, // 1h30
-          { position: 2, color: 'red' }, // 3h
-          { position: 3, color: 'neutral' }, // 4h30
-          { position: 4, color: 'neutral' }, // 6h
-          { position: 5, color: 'neutral' }, // 7h30
-          { position: 6, color: 'red' }, // 9h
-          { position: 7, color: 'neutral' }, // 10h30
+          { position: 0, color: 'neutral', label: '12h' },
+          { position: 1, color: 'neutral', label: '1h30' },
+          { position: 2, color: 'red', label: '3h' },
+          { position: 3, color: 'neutral', label: '4h30' },
+          { position: 4, color: 'neutral', label: '6h' },
+          { position: 5, color: 'neutral', label: '7h30' },
+          { position: 6, color: 'red', label: '9h' },
+          { position: 7, color: 'neutral', label: '10h30' },
         ]}
       />
     )
@@ -272,9 +387,9 @@ export const ThreeDots = {
         value={value}
         onChange={setValue}
         dots={[
-          { position: 0, color: 'neutral', default: true },
-          { position: 2, color: 'red' },
-          { position: 4, color: 'neutral' },
+          { position: 0, color: 'neutral', default: true, label: 'Top' },
+          { position: 2, color: 'red', label: 'Right' },
+          { position: 4, color: 'neutral', label: 'Bottom' },
         ]}
       />
     )