@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/actions/relative-data/relative-data.tsx

@@ -1,187 +1,106 @@
-import { IconButton } from '@mui/material'
-import { PercentOutlined } from '@mui/icons-material'
-import { useCallback, useEffect, useRef } from 'react'
-import { widgetStoreActions } from '../../stores/widget-store'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
-import type { RelativeDataProps, RelativeDataState } from './types'
-import { actionButtonStyles } from '../shared/styles'
+import { useEffect, useMemo, type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import { Percent as PercentIcon } from '@mui/icons-material'
 import { Tooltip } from '../../../components'
-import { calculateTotal, toRelativeData } from './utils'
-import type { EchartWidgetData } from '../../../widgets/echart'
+import {
+  getWidgetStore,
+  useSingleTransform,
+  useWidget,
+  useWidgetId,
+} from '../../stores'
+import { createPercentFormatter, toRelativeData } from './transforms'
+import { DEFAULT_RELATIVE_DATA_LABELS, type RelativeDataLabels } from './labels'
+import { styles } from './style'
+
+const DATA_DESCRIPTOR = {
+  id: 'relative-data',
+  type: 'data' as const,
+  order: 15,
+}
 
-export const RELATIVE_DATA_TOOL_ID = 'relative-data'
-export const RELATIVE_DATA_CONFIG_TOOL_ID = 'relative-data-config'
+export interface RelativeDataProps {
+  initialEnabled?: boolean
+  /**
+   * BCP-47 locale tag forwarded to `Intl.NumberFormat`. Defaults to the
+   * runtime locale.
+   */
+  locale?: string
+  labels?: Partial<RelativeDataLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Data-side transform that rewrites the widget's series into their
+   * relative (0–100) form. Defaults to {@link toRelativeData}, which
+   * handles the canonical `{ name, value }[]` shape (bar / pie /
+   * timeseries / category). Widgets with a different data shape pass
+   * their own — `toRelativeHistogramData` for histogram's `number[]`,
+   * `toRelativeScatterplotData` for scatter's `[x, y][]`.
+   *
+   * Should be a stable top-level reference; inline `(data) => ...`
+   * literals re-register the transform every render.
+   */
+  transform?: (data: unknown) => unknown
+}
 
 /**
- * Widget action to toggle between relative (percentage) and absolute data display.
- *
- * Registers two transformation tools in the widget pipeline when mounted:
- * - A data tool that converts values to percentages (enabled/disabled via store)
- * - A config tool that is **always enabled** and reads `isRelative` from the store
- *   to decide whether to apply the percentage formatter or restore the original one.
- *   The config tool must always participate because the original formatter may have
- *   been set via `setWidget` (not in the base config), so disabling the tool would
- *   leave the percentage formatter stuck on the widget.
+ * Toggle between absolute and relative (percentage) values.
  *
- * @example
- * ```tsx
- * <RelativeData
- *   id="my-widget"
- *   order={20}
- *   defaultIsRelative={false}
- * />
- * ```
+ *   - **Data side**: a single data transform ({@link toRelativeData}) registered
+ *     through `useSingleTransform`. When disabled, the pipeline skips it and the
+ *     derived `data` reverts to `rawData` automatically.
+ *   - **Formatter side**: an effect writes directly to `state.formatter`. When
+ *     enabled it installs the Intl-based percent formatter; when disabled it
+ *     reads `state.rawFormatter` (the consumer-supplied original, always live)
+ *     and writes it back to `formatter`. No "original" snapshot is captured —
+ *     `rawFormatter` is the original.
  */
 export function RelativeData({
-  id,
-  order = 10,
-  defaultIsRelative = false,
+  initialEnabled = false,
+  locale,
   labels,
-  Icon,
-  IconButtonProps,
+  icon: Icon = PercentIcon,
+  iconProps,
+  transform,
 }: RelativeDataProps) {
-  const percentFormatterRef = useRef<((value: number) => string) | undefined>(
-    undefined,
+  const id = useWidgetId()
+  const _labels = { ...DEFAULT_RELATIVE_DATA_LABELS, ...labels }
+
+  const { enabled, toggle } = useSingleTransform(
+    id,
+    DATA_DESCRIPTOR,
+    transform ?? toRelativeData,
+    { initialEnabled },
   )
 
-  // Read isRelative from widget store root — single source of truth
-  const { isRelative } = useWidgetSelector(id, (w) => ({
-    isRelative:
-      (w as RelativeDataState | undefined)?.isRelative ?? defaultIsRelative,
-  }))
-
-  // Initialize store with default value on mount.
-  // When defaultIsRelative=true, capture originals so toggling OFF can restore them.
-  useEffect(() => {
-    const current = widgetStoreActions.getWidget<RelativeDataState>(id)
-    if (current?.isRelative === undefined) {
-      if (defaultIsRelative) {
-        widgetStoreActions.setWidget(id, {
-          isRelative: true,
-          originalFormatter: current?.formatter,
-          originalMax: (current as unknown as Record<string, number>)?.max,
-        })
-      } else {
-        widgetStoreActions.setWidget(id, { isRelative: defaultIsRelative })
-      }
-    }
-  }, [id, defaultIsRelative])
-
-  // Register data tool once — fn has no closure deps
-  useEffect(() => {
-    widgetStoreActions.registerTool(id, {
-      id: RELATIVE_DATA_TOOL_ID,
-      order,
-      enabled: defaultIsRelative,
-      fn: (data) => {
-        const echartData = data as EchartWidgetData
-        const total = calculateTotal(echartData)
-        return toRelativeData(echartData, total)
-      },
-    })
-
-    return () => widgetStoreActions.unregisterTool(id, RELATIVE_DATA_TOOL_ID)
-  }, [id, order, defaultIsRelative])
+  const percentFormatter = useMemo(
+    () => createPercentFormatter(locale),
+    [locale],
+  )
 
-  // Sync data tool enabled — lightweight, no re-registration
-  useEffect(() => {
-    widgetStoreActions.setToolEnabled(id, RELATIVE_DATA_TOOL_ID, isRelative)
-  }, [id, isRelative])
+  // Subscribe to rawFormatter so the effect re-runs and re-applies after the
+  // consumer's formatter prop changes (Provider syncs the new prop to both
+  // rawFormatter and formatter — re-applying restores the percent override
+  // when relative is on, and tracks the new rawFormatter when off).
+  const rawFormatter = useWidget(id, (s) => s.rawFormatter)
 
-  // Register config tool — ALWAYS enabled.
-  // Reads isRelative, originalFormatter, originalMax from the store at execution time:
-  // - isRelative=true  → applies percentage formatter and max=100
-  // - isRelative=false → restores original formatter/max from store
   useEffect(() => {
-    widgetStoreActions.registerTool(id, {
-      id: RELATIVE_DATA_CONFIG_TOOL_ID,
-      type: 'config',
-      order,
-      enabled: true,
-      fn: (currentConfig: unknown) => {
-        const config = currentConfig as Record<string, unknown>
-        const widget = widgetStoreActions.getWidget<RelativeDataState>(id)
-
-        const hasSourceData =
-          widget?.sourceData != null &&
-          !(Array.isArray(widget.sourceData) && widget.sourceData.length === 0)
-
-        if (widget?.isRelative) {
-          // Don't apply percentage formatter when there's no source data
-          if (!hasSourceData) return config
-
-          if (!percentFormatterRef.current) {
-            const locale = widget?.locale
-            percentFormatterRef.current = (value: number) =>
-              new Intl.NumberFormat(locale, {
-                style: 'percent',
-                minimumFractionDigits: 1,
-                maximumFractionDigits: 1,
-              }).format(value / 100)
-          }
-          return { ...config, formatter: percentFormatterRef.current, max: 100 }
-        }
-
-        // Not in relative mode — restore originals from store if captured.
-        // Use `in` because originalFormatter may have been captured as undefined
-        // (widget had no formatter before toggling relative on).
-        percentFormatterRef.current = undefined
-        if (widget != null && 'originalFormatter' in widget) {
-          return {
-            ...config,
-            formatter: widget.originalFormatter,
-            max: widget.originalMax,
-          }
-        }
-        return config
-      },
+    getWidgetStore(id).setState({
+      formatter: enabled ? percentFormatter : rawFormatter,
     })
-    return () => {
-      // Restore original formatter/max if unmounting while in relative mode
-      const widget = widgetStoreActions.getWidget<RelativeDataState>(id)
-      if (widget?.isRelative && 'originalFormatter' in widget) {
-        widgetStoreActions.setWidget(id, {
-          formatter: widget.originalFormatter,
-          max: widget.originalMax,
-        })
-      }
-      percentFormatterRef.current = undefined
-      widgetStoreActions.unregisterTool(id, RELATIVE_DATA_CONFIG_TOOL_ID)
-    }
-  }, [id, order, defaultIsRelative])
-
-  const handleToggle = useCallback(() => {
-    const newIsRelative = !isRelative
-    percentFormatterRef.current = undefined
-
-    if (newIsRelative) {
-      // Capture current formatter/max in store before switching to relative
-      const widget = widgetStoreActions.getWidget(id)
-      widgetStoreActions.setWidget(id, {
-        isRelative: true,
-        originalFormatter: widget?.formatter,
-        originalMax: (widget as unknown as Record<string, unknown>)?.max,
-      })
-    } else {
-      widgetStoreActions.setWidget(id, { isRelative: false })
-    }
-  }, [isRelative, id])
+  }, [id, enabled, percentFormatter, rawFormatter])
 
-  const tooltipLabel = isRelative
-    ? (labels?.absolute ?? 'Show absolute values')
-    : (labels?.relative ?? 'Show relative values')
+  const tooltip = enabled ? _labels.on : _labels.off
 
   return (
-    <Tooltip title={tooltipLabel}>
+    <Tooltip title={tooltip}>
       <IconButton
         size='small'
-        aria-label={labels?.ariaLabel ?? tooltipLabel}
-        onClick={handleToggle}
-        sx={actionButtonStyles.trigger}
-        data-active={isRelative}
-        {...IconButtonProps}
+        aria-label={tooltip}
+        aria-pressed={enabled}
+        onClick={toggle}
+        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
       >
-        {Icon ?? <PercentOutlined />}
+        <Icon fontSize='small' {...iconProps} />
       </IconButton>
     </Tooltip>
   )

package/src/{widgets-v2 → widgets}/actions/relative-data/transforms.ts

@@ -8,8 +8,8 @@
  * Used by widgets whose series are arrays of `{ name, value }`
  * objects — bar, pie, timeseries, category. Widgets with a different
  * data shape pass their own transform via
- * `<RelativeData transform={...} />`; see `widgets-v2/histogram` and
- * `widgets-v2/scatterplot` for in-tree examples.
+ * `<RelativeData transform={...} />`; see `widgets/histogram` and
+ * `widgets/scatterplot` for in-tree examples.
  *
  * The denominator is the sum of |value| across the series so mixed-sign
  * series (e.g. cashflow with inflows + outflows) produce sane signed

package/src/widgets/actions/searcher/searcher-toggle.tsx

@@ -1,72 +1,91 @@
-import { IconButton } from '@mui/material'
-import { SearchOutlined } from '@mui/icons-material'
-import { useCallback, useEffect } from 'react'
-import type { SearcherToggleProps, SearcherState } from './types'
-import { actionButtonStyles } from '../shared/styles'
+import { useCallback, type ComponentType } from 'react'
+import { IconButton, type SvgIconProps } from '@mui/material'
+import { Search as SearchIcon } from '@mui/icons-material'
 import { Tooltip } from '../../../components'
-import { widgetStoreActions } from '../../stores/widget-store'
-import { useWidgetSelector } from '../../stores/use-widget-selector'
+import {
+  getWidgetStore,
+  useSingleTransform,
+  useWidget,
+  useWidgetId,
+} from '../../stores'
+import { filterBySearchText } from './filter'
+import { DEFAULT_SEARCHER_LABELS, type SearcherLabels } from './labels'
+import { styles } from './style'
+
+const SEARCHER_DESCRIPTOR = {
+  id: 'searcher',
+  type: 'data' as const,
+  order: 20,
+  disables: ['lock-selection'],
+}
+
+export interface SearcherToggleProps {
+  labels?: Partial<SearcherLabels>
+  icon?: ComponentType<SvgIconProps>
+  iconProps?: SvgIconProps
+  /**
+   * Whether the searcher transform is enabled on first mount. Defaults
+   * to `false` so the toggle renders un-pressed and the
+   * `filterBySearchText` transform stays dormant until the user clicks
+   * it. Set to `true` for search-first widgets where the input is the
+   * primary affordance.
+   */
+  initialEnabled?: boolean
+}
 
-/**
- * Widget action button to toggle search functionality.
- *
- * Stores the enabled state in the widget store using the provided id.
- * When search is active, the button shows an active state with a light background.
- * Use in conjunction with the Searcher component to display the search input.
- *
- * @example
- * ```tsx
- * <SearcherToggle id="my-widget" />
- * <Searcher
- *   id="my-widget"
- *   data={widgetData}
- * />
- * ```
- */
 export function SearcherToggle({
-  id,
-  defaultEnabled = false,
   labels,
-  Icon,
-  IconButtonProps,
+  icon: Icon = SearchIcon,
+  iconProps,
+  initialEnabled = false,
 }: SearcherToggleProps) {
-  const { storeIsEnabled } = useWidgetSelector(id, (w) => ({
-    storeIsEnabled: (w as SearcherState | undefined)?.isSearchEnabled,
-  }))
-
-  const isEnabled = storeIsEnabled ?? defaultEnabled
-
-  // Initialize store with default value on mount
-  useEffect(() => {
-    const currentValue =
-      widgetStoreActions.getWidget<SearcherState>(id)?.isSearchEnabled
-    if (currentValue === undefined) {
-      widgetStoreActions.setWidget(id, { isSearchEnabled: defaultEnabled })
-    }
-  }, [defaultEnabled, id])
-
-  const handleToggle = useCallback(() => {
-    widgetStoreActions.setWidget(id, { isSearchEnabled: !isEnabled })
-  }, [id, isEnabled])
+  const id = useWidgetId()
+  const resolved = { ...DEFAULT_SEARCHER_LABELS, ...labels }
+  const text = useWidget(
+    id,
+    (s) => (s.transformStates.searcher?.searchText as string | undefined) ?? '',
+  )
 
-  const tooltipLabel = isEnabled
-    ? (labels?.disable ?? 'Disable search')
-    : (labels?.enable ?? 'Enable search')
+  // The transform fn closes over `text`. Memoize via useCallback so identity
+  // only changes when text changes, allowing useTransform to re-register.
+  const fn = useCallback(
+    (data: unknown) => filterBySearchText(data, text),
+    [text],
+  )
 
-  const ariaLabel = labels?.ariaLabel ?? tooltipLabel
+  const { enabled, toggle } = useSingleTransform(id, SEARCHER_DESCRIPTOR, fn, {
+    initialEnabled,
+  })
 
   return (
-    <Tooltip title={tooltipLabel}>
+    <Tooltip title={resolved.toggle}>
       <IconButton
         size='small'
-        aria-label={ariaLabel}
-        onClick={handleToggle}
-        sx={actionButtonStyles.trigger}
-        data-active={isEnabled}
-        {...IconButtonProps}
+        aria-label={resolved.toggle}
+        aria-pressed={enabled}
+        onClick={toggle}
+        sx={{ ...styles.toggle, ...(enabled && styles.toggleActive) }}
       >
-        {Icon ?? <SearchOutlined fontSize='small' />}
+        <Icon fontSize='small' {...iconProps} />
       </IconButton>
     </Tooltip>
   )
 }
+
+/**
+ * Imperatively writes the search text into the widget store. Used by the
+ * Searcher input to update text inside transformStates without going through
+ * a re-rendered React subscription.
+ */
+export function setSearcherText(widgetId: string, value: string): void {
+  getWidgetStore(widgetId).setState((s) => ({
+    transformStates: {
+      ...s.transformStates,
+      searcher: {
+        enabled: s.transformStates.searcher?.enabled ?? false,
+        ...s.transformStates.searcher,
+        searchText: value,
+      },
+    },
+  }))
+}