@carto/ps-react-ui 5.1.0 → 6.0.0

package/src/widgets/stores/index.ts

@@ -1,13 +1,49 @@
-export { useWidgetStore, widgetStoreActions } from './widget-store'
-export { useWidgetSelector } from './use-widget-selector'
 export type {
-  BaseWidgetState,
-  ToolRegistration,
-  ToolTransformFunction,
-  ToolType,
-  WidgetsStoreProps,
+  TransformType,
+  TransformDescriptor,
+  TransformFn,
+  Transform,
+  TransformPair,
   WidgetState,
-  WidgetStore,
-  WidgetStoreActions,
-  WidgetStoreState,
+  WidgetInit,
+  WidgetStoreApi,
 } from './types'
+
+export { applyTransforms, upsertTransform, removeTransform } from './transforms'
+
+export { pipelineMiddleware } from './pipeline-middleware'
+
+export { WidgetContext, useWidgetId } from './widget-context'
+
+export {
+  getWidgetStore,
+  hasWidgetStore,
+  deleteWidgetStore,
+  resetWidgetStore,
+  clearAllWidgetStores,
+  registerWidgetStore,
+  unregisterWidgetStore,
+  setWidgetStoreEntry,
+  createWidgetStore,
+  useWidget,
+  useWidgetShallow,
+  setCaptureEl,
+  getCaptureEl,
+  clearAllCaptureEls,
+  setEchartInstance,
+  getEchartInstance,
+  subscribeEchartInstance,
+  clearAllEchartInstances,
+  __debugListWidgetStores,
+} from './widget-store-registry'
+
+export { useEchartInstance } from './use-echart-instance'
+
+export {
+  useTransform,
+  useSingleTransform,
+  type UseTransformOptions,
+  type TransformControls,
+} from './use-transform'
+
+export { useTransformEnabled } from './use-transform-enabled'

package/src/{widgets-v2 → widgets}/stores/transforms.ts

@@ -20,7 +20,7 @@ export function applyTransforms(
     } catch (e) {
       const err = e instanceof Error ? e : new Error(String(e))
       // eslint-disable-next-line no-console
-      console.warn(`[widgets-v2] Transform "${t.id}" failed:`, err)
+      console.warn(`[widgets] Transform "${t.id}" failed:`, err)
       onError?.(t.id, err)
     }
   }

package/src/widgets/stores/types.ts

@@ -1,203 +1,64 @@
-import type { RefObject } from 'react'
+import type { StoreApi } from 'zustand'
 
-/**
- * Tool type determines which pipeline a tool participates in.
- * - 'data': transforms widget data (default)
- * - 'config': transforms widget config/option
- */
-export type ToolType = 'data' | 'config'
+export type TransformType = 'data' | 'config'
 
-export interface WidgetsStoreProps {
-  /** Unique identifier for the widget */
+export interface TransformDescriptor {
   id: string
-  /** Type of widget */
-  type: string
-  /** Widget data - flexible to accommodate different widget types */
-  data: unknown
-  /** Original pre-pipeline data. Used by NoData to distinguish
-   *  "no data from API" from "pipeline tools filtered everything out".
-   *  Set automatically by executeToolPipeline — not a component prop. */
-  sourceData?: unknown
-  /** Loading state */
-  isLoading: boolean
-  /** Fetching state (e.g., for async data) */
-  isFetching: boolean
-  /** Error message if any */
-  error?: {
-    title?: string
-    message?: string
-  }
-  /** Whether widget is visible */
-  visible?: boolean
-  /** Reference to the widget ui instance */
-  refUI?: RefObject<HTMLElement | null>
-  /** Registered tools for the widget's transformation pipeline */
-  registeredTools?: ToolRegistration[]
-  /** Formatter function for widget values */
-  formatter?: (value: number) => string
-  /** Formatter function for widget label/category values */
-  labelFormatter?: (value: string | number) => string | number
-  /** Locale for number formatting (e.g., 'en-US', 'es-ES', 'fr-FR') */
-  locale?: string
-}
-
-/**
- * Tool transformation function type
- * Can be synchronous or asynchronous to support remote operations
- */
-export type ToolTransformFunction = (data: unknown) => unknown
-
-/**
- * Tool registration for widget pipeline
- *
- * @example Basic tool registration
- * ```typescript
- * registerTool(widgetId, {
- *   id: 'searcher',
- *   order: 10,
- *   enabled: true,
- *   fn: (data) => filterData(data),
- * })
- * ```
- *
- * @example Tool with dependencies
- * ```typescript
- * registerTool(widgetId, {
- *   id: 'lock-selection',
- *   order: 20,
- *   enabled: true,
- *   fn: (data) => lockData(data),
- *   disables: ['searcher', 'relative-data'], // Disable these when active
- * })
- * ```
- *
- * Dependency Management:
- * - Multiple tools can disable the same target (reference counting)
- * - Target is only re-enabled when ALL disabling tools are inactive
- * - Original enabled state is preserved and restored
- * - Circular dependencies are detected and throw errors
- */
-export interface ToolRegistration {
-  /** Unique tool identifier (e.g., 'searcher', 'relative-data') */
-  id: string
-  /** Execution priority - lower numbers execute first */
+  type: TransformType
   order: number
-  /** Transformation function */
-  fn: ToolTransformFunction
-  /** Whether tool is currently enabled */
-  enabled: boolean
-  /** 'data' (default) transforms data, 'config' transforms widget config/option */
-  type?: ToolType
-  /**
-   * Array of tool IDs to disable when this tool is active.
-   * During pipeline execution, if this tool is enabled, any tools listed
-   * in this array will be excluded from the pipeline.
-   *
-   * @example
-   * ```typescript
-   * disables: ['searcher', 'relative-data']
-   * ```
-   */
   disables?: string[]
+  replaceMergeKeys?: string[]
 }
 
-/**
- * Base widget state interface
- */
-export type BaseWidgetState<T> = WidgetsStoreProps & T
-
-/**
- * Union type for all widget states
- */
-export type WidgetState = BaseWidgetState<unknown>
+export type TransformFn = (input: unknown) => unknown
 
-/**
- * Widget store state with tool registration
- */
-export interface WidgetStoreState {
-  /** Map of widget id to widget state */
-  widgets: Record<string, WidgetState>
+export interface Transform extends TransformDescriptor {
+  fn: TransformFn
+  enabled: boolean
 }
 
-/**
- * Widget store actions
- */
-export interface WidgetStoreActions {
-  /**
-   * Add or update a widget in the store
-   * @param id - Widget ID
-   * @param widget - Widget state properties to merge (accepts any object structure)
-   * @template T - Type of the widget state for type-safe access
-   */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  setWidget: <T = any>(id: WidgetState['id'], widget: Partial<T>) => void
-
-  /**
-   * Remove a widget from the store
-   * @param id - Widget ID to remove
-   */
-  removeWidget: (id: WidgetState['id']) => void
-
-  /**
-   * Clear all widgets
-   */
-  clearWidgets: () => void
+export interface TransformPair {
+  descriptor: TransformDescriptor
+  fn: TransformFn
+}
 
-  /**
-   * Get widget by ID
-   * @param id - Widget ID
-   * @returns Widget state or undefined if not found
-   */
-  getWidget: <T extends WidgetState = WidgetState>(
-    id: WidgetState['id'],
-  ) => T | undefined
+export interface WidgetState {
+  rawData: unknown
+  data: unknown
 
-  /**
-   * Register a tool with the widget's transformation pipeline
-   * @param widgetId - Widget ID
-   * @param tool - Tool registration object
-   */
-  registerTool: (widgetId: string, tool: ToolRegistration) => void
+  dataTransforms: readonly Transform[]
+  configTransforms: readonly Transform[]
 
-  /**
-   * Unregister a tool from the widget's transformation pipeline
-   * @param widgetId - Widget ID
-   * @param toolId - Tool ID to remove
-   */
-  unregisterTool: (widgetId: string, toolId: string) => void
+  transformStates: Record<string, { enabled: boolean; [k: string]: unknown }>
 
-  /**
-   * Set tool enabled state
-   * @param widgetId - Widget ID
-   * @param toolId - Tool ID
-   * @param enabled - Whether tool should be enabled
-   */
-  setToolEnabled: (widgetId: string, toolId: string, enabled: boolean) => void
+  isLoading: boolean
+  isFetching: boolean
+  error: unknown
 
   /**
-   * Trigger pipeline re-execution by bumping the registeredTools reference.
-   * @param widgetId - Widget ID
+   * Original formatter as supplied by the consumer (Provider's `formatter`
+   * prop). Always live-synced — never overridden by actions. Actions that need
+   * to display a different formatter (e.g. {@link RelativeData}'s percent
+   * formatter) should write to {@link WidgetState.formatter} and read this
+   * field when restoring the absolute view.
    */
-  triggerToolPipeline: (widgetId: string) => void
-
+  rawFormatter?: (value: number) => string
   /**
-   * Execute the tool transformation pipeline
-   * Supports both synchronous and asynchronous tools
-   * @param widgetId - Widget ID
-   * @param sourceData - Original data to transform
+   * Active formatter — what consumer code (tooltips, axis labels, legends,
+   * etc.) reads. Defaults to {@link WidgetState.rawFormatter}; actions may
+   * override it temporarily and restore it from `rawFormatter` later.
    */
-  executeToolPipeline: (widgetId: string, sourceData: unknown) => Promise<void>
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
+}
 
-  /**
-   * Execute the config transformation pipeline
-   * Applies config-type tools to the base config, then sets the result on the widget
-   * @param widgetId - Widget ID
-   * @param baseConfig - Base config to transform
-   */
-  executeConfigPipeline: (widgetId: string, baseConfig: object) => Promise<void>
+export interface WidgetInit {
+  data: unknown
+  isLoading?: boolean
+  isFetching?: boolean
+  error?: unknown
+  formatter?: (value: number) => string
+  labelFormatter?: (value: string | number) => string | number
 }
 
-/**
- * Complete widget store interface
- */
-export type WidgetStore = WidgetStoreState & WidgetStoreActions
+export type WidgetStoreApi = StoreApi<WidgetState>

package/src/{widgets-v2 → widgets}/stores/use-transform.ts

@@ -40,7 +40,7 @@ export function useTransform(
   options?: UseTransformOptions,
 ): TransformControls {
   if (pairs.length === 0) {
-    throw new Error('[widgets-v2] useTransform requires at least one pair.')
+    throw new Error('[widgets] useTransform requires at least one pair.')
   }
 
   const store = getWidgetStore(id)

package/src/{widgets-v2 → widgets}/stores/widget-store-registry.ts

@@ -40,7 +40,7 @@ const echartInstanceSubscribers = new Map<string, Set<EchartInstanceListener>>()
 
 export function getWidgetStore(id: string): WidgetStoreApi {
   const store = widgetStores.get(id)
-  if (!store) throw new Error(`[widgets-v2] Widget store "${id}" not found.`)
+  if (!store) throw new Error(`[widgets] Widget store "${id}" not found.`)
   return store
 }
 
@@ -200,7 +200,7 @@ export function registerWidgetStore(id: string, store: WidgetStoreApi): void {
   if (count > 1 && isDev() && !warnedDuplicates.has(id)) {
     // eslint-disable-next-line no-console
     console.warn(
-      `[widgets-v2] Duplicate <Widget.Provider id="${id}"> detected. ` +
+      `[widgets] Duplicate <Widget.Provider id="${id}"> detected. ` +
         `Multiple providers sharing an id will race on prop sync and corrupt the store. ` +
         `Use unique ids per widget instance.`,
     )

package/src/widgets/subheader/style.ts

@@ -2,19 +2,11 @@ import type { SxProps, Theme } from '@mui/material'
 
 export const styles = {
   root: {
-    display: 'flex',
+    display: 'grid',
+    gridTemplateColumns: '1fr auto',
     alignItems: 'center',
-    gap: ({ spacing }) => spacing(1),
-    minHeight: ({ spacing }) => spacing(3),
-  },
-  slotLeft: {
-    flexShrink: 0,
-  },
-  slotRight: {
-    flexGrow: 1,
-    display: 'flex',
-    justifyContent: 'flex-end',
-    alignItems: 'center',
-    gap: ({ spacing }) => spacing(1),
+    gap: 1,
+    minHeight: 32,
+    pb: 1,
   },
 } satisfies Record<string, SxProps<Theme>>

package/src/widgets/subheader/subheader.test.tsx

@@ -1,45 +1,30 @@
-import { describe, test, expect } from 'vitest'
-import { render, screen } from '@testing-library/react'
-import { WidgetSubHeader } from './subheader'
+import { describe, it, expect } from 'vitest'
+import { render } from '@testing-library/react'
+import { Subheader } from './subheader'
 
-describe('WidgetSubHeader', () => {
-  test('renders empty right slot by default', () => {
-    const { container } = render(<WidgetSubHeader />)
-    expect(container.firstChild).toBeTruthy()
-  })
-
-  test('renders slotLeft content', () => {
-    render(<WidgetSubHeader slotLeft={<span>Left Content</span>} />)
-    expect(screen.getByText('Left Content')).toBeTruthy()
-  })
-
-  test('renders slotRight content', () => {
-    render(<WidgetSubHeader slotRight={<span>Right Content</span>} />)
-    expect(screen.getByText('Right Content')).toBeTruthy()
-  })
-
-  test('renders both slots when provided', () => {
-    render(
-      <WidgetSubHeader
-        slotLeft={<span>Left</span>}
-        slotRight={<span>Right</span>}
-      />,
+describe('<Subheader>', () => {
+  it('renders children inside a Box', () => {
+    const { getByText } = render(
+      <Subheader>
+        <span>left</span>
+        <span>right</span>
+      </Subheader>,
     )
-    expect(screen.getByText('Left')).toBeTruthy()
-    expect(screen.getByText('Right')).toBeTruthy()
-  })
-
-  test('right slot takes full width when left is empty (flex layout)', () => {
-    const { container } = render(<WidgetSubHeader />)
-    // The right slot should have flexGrow: 1 for full width behavior
-    const rightSlot = container.querySelector('[class*="MuiBox-root"]')
-    expect(rightSlot).toBeTruthy()
+    expect(getByText('left')).toBeTruthy()
+    expect(getByText('right')).toBeTruthy()
   })
 
-  test('renders with custom sx prop', () => {
+  it('merges caller-supplied sx onto the root', () => {
     const { container } = render(
-      <WidgetSubHeader sx={{ backgroundColor: 'red' }} />,
+      <Subheader sx={{ mt: 4 }}>
+        <span>x</span>
+      </Subheader>,
     )
-    expect(container.firstChild).toBeTruthy()
+    expect(container.firstChild).not.toBeNull()
+    // Class-based assertions are brittle; settle for "an element renders + a
+    // single child slot exists" — sx forwarding gets exercised at the
+    // import/MUI level so we don't need to inspect emotion-generated class
+    // names.
+    expect(container.querySelectorAll('span').length).toBe(1)
   })
 })

package/src/widgets/subheader/subheader.tsx

@@ -1,35 +1,16 @@
-import { Box } from '@mui/material'
+import { Box, type SxProps, type Theme } from '@mui/material'
+import type { ReactNode } from 'react'
 import { styles } from './style'
-import type { WidgetSubHeaderProps } from './types'
+
+export interface SubheaderProps {
+  sx?: SxProps<Theme>
+  children: ReactNode
+}
 
 /**
- * Flexible two-slot layout for displaying supplementary widget information such as totals, timestamps, or controls. Uses flexbox with space-between justification.
- *
- * @example
- * ```tsx
- * <WidgetSubHeader
- *   slotLeft={<Typography variant="caption">Total: 1,234</Typography>}
- *   slotRight={<Typography variant="caption">Updated: 2m ago</Typography>}
- * />
- * ```
+ * Stateless layout: CSS grid `1fr auto`. Children self-place — typically
+ * `<Widget.SelectionSummary />` (left) and `<Widget.Toolbox>` (right).
  */
-export function WidgetSubHeader({
-  slotLeft,
-  slotRight,
-  sx,
-}: WidgetSubHeaderProps) {
-  return (
-    <Box sx={{ ...styles.root, ...sx }} className='widget-subheader'>
-      {slotLeft && (
-        <Box sx={styles.slotLeft} className='widget-subheader-slot-left'>
-          {slotLeft}
-        </Box>
-      )}
-      {slotRight && (
-        <Box sx={styles.slotRight} className='widget-subheader-slot-right'>
-          {slotRight}
-        </Box>
-      )}
-    </Box>
-  )
+export function Subheader({ sx, children }: SubheaderProps) {
+  return <Box sx={{ ...styles.root, ...sx }}>{children}</Box>
 }